Media & Presentation
Carousel
Carousel displays swipeable or button-driven slide content (Embla Carousel). Give media a predictable place in the layout while keeping the surrounding content readable during loading, playback or failure. Import it from @/components/kamod-ui/carousel.
Source · Design reference · API reference · Theming · Styles
Interactive preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthInstallation
Depends on embla-carousel and optional embla-carousel-autoplay (used when autoplay is set). Import primitives from @/components/kamod-ui/carousel.
pnpm add @kamod-ch/uiCopy an example with @kamod-ch/ui or the matching @kamod-ch/ui/… subpath. The code block switches between those two installs. Connect The Global Theme CSS and Tailwind Source Detection before your first render.
Usage
Wrap slides in CarouselContent; each slide is a CarouselItem. Place CarouselPrevious and CarouselNext as siblings of CarouselContent inside Carousel. Use opts for Embla options (align, loop, direction). Use setApi to read scrollSnapList, selectedScrollSnap, and events.
import { Carousel } from "@kamod-ch/ui";Choose a complete composition from the examples below; required child components and props vary by pattern.
Component Examples & Variants
Explore Carousel in Different Contexts, from the starting pattern to the compositions below. Begin with Demo, then compare the examples that match your content, state and layout. These are working patterns to adapt, not a list of interchangeable variant values: check the API Reference before using a prop or combining behaviors. Look at the surrounding labels, supporting text and spacing as well as the component itself.
Read the Result and Its Implementation Together. Use each showcase’s Code view to inspect imports and composition, or its Prompt view to prepare a setup or adaptation brief. Try the narrow preview and local theme controls before connecting real data, and use Reset to return an example to its initial state. Keep layout changes in class utilities where appropriate; follow the Component Styles Guide for hierarchy and the Theming Guide for shared surfaces and colors. The Accessibility Notes explain what to preserve when making those changes.
Demo
Keep Slide Navigation Discoverable. Compose CarouselItem slides with previous and next controls around the viewport. Each slide remains a card-like content unit; the carousel manages which part of the sequence is visible and how readers move through it.
Make each slide useful independently, and avoid putting essential sequential instructions into a carousel that encourages readers to skip directly between items.
// See previewCode hero — CarouselContent + Items + Prev/Next.Sizes
Show Enough of the Next Item to Suggest Continuation. Use basis-* utilities on CarouselItem to control how many slides fit at once. Set opts.align to start when the leading edge should anchor each scroll position rather than centering the selected slide.
Check the longest content at each breakpoint, and keep the chosen alignment consistent with how the surrounding page reads.
Interactive preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthSpacing
Treat Spacing as a Paired Adjustment. Pair a negative margin on CarouselContent with matching padding on each item. This creates regular gaps between slides while keeping the first slide aligned with the outer viewport boundary.
Change both sides consistently, and inspect the outer edges so the carousel does not appear indented or clipped relative to nearby content.
Interactive preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthOrientation
Give the Vertical Viewport an Explicit Boundary. A vertical carousel needs a constrained height as well as an orientation change. Size CarouselContent, allow its viewport to shrink with min-h-0, and reserve space for the controls above and below the slides.
Test wheel, touch and keyboard interaction when the carousel sits inside another scrolling region. Avoid trapping long slide text in a viewport too short to read, and confirm that both navigation controls remain reachable.
Interactive preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthOptions
Choose Movement Rules for the Content. Pass behavior options such as loop through opts to configure the underlying Embla instance. The wrapper combines those settings with its own orientation and direction, keeping the outer component responsible for the layout contract.
Review the forwarded options alongside the API Reference, and test boundary navigation after changing alignment, direction or looping.
Interactive preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthAPI
Observe the Carousel without Duplicating Its State. Use setApi to access the carousel instance when an external counter or control needs its current position. Subscribe to selection changes to keep the supporting UI synchronized with dragging as well as button navigation.
Remove event listeners when the instance changes or the component unmounts, and initialize derived text before the first user interaction so it does not start out stale.
Interactive preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthAutoplay
Keep Automatic Movement under User Control. Use the autoplay prop for the built-in playback option, or supply plugins when the integration needs additional Embla behavior. Movement should remain understandable alongside the same manual previous and next controls.
Provide an appropriate pause strategy, consider reduced-motion preferences, and stop any application-owned timers during cleanup; use manual navigation when the content requires sustained attention.
Interactive preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthProps and Data
Configure Carousel using the contracts below. Read the documented options alongside the Source Definitions to understand which values your application supplies and which details the component owns. Start with a prop or helper, then follow its type link to inspect the declaration without leaving the page.
Props, slots and variants for this component.
Type cards are extracted from this checkout’s TypeScript source at build time. Props inherited through HTMLAttributes, Omit or variant helpers remain references in those declarations; their fields are not flattened here. Match the reference to your installed version, and check a package’s exports before writing an import type. A type exported by a source file is not necessarily re-exported by @kamod-ch/ui.
Component Props
? means a field can be omitted; it does not promise a fallback value. Existing documented defaults remain alongside the descriptions. For callbacks, check the argument and return types before connecting your own state or services.Carousel
CarouselProps
| Prop / type | Description |
|---|---|
autoplay | When `plugins` is omitted, adds `embla-carousel-autoplay`. Ignored if `plugins` is set.
|
children | Configure
|
class | Configure
|
dir | Configure
|
label | Accessible name for the carousel region.
|
opts | Configure
|
orientation | Configure
|
plugins | Configure
|
setApi | Configure
|
CarouselAutoplayPause
CarouselAutoplayPauseProps
| Prop / type | Description |
|---|---|
class | Configure
|
onClick | Configure
|
CarouselContent
CarouselContentProps
| Prop / type | Description |
|---|---|
children | Configure
|
class | Configure
|
CarouselItem
CarouselItemProps
| Prop / type | Description |
|---|---|
children | Configure
|
class | Configure
|
CarouselNext
CarouselNextProps
| Prop / type | Description |
|---|---|
children | Configure
|
class | Configure
|
disabled | Configure
|
onClick | Configure
|
CarouselPrevious
CarouselPreviousProps
| Prop / type | Description |
|---|---|
children | Configure
|
class | Configure
|
disabled | Configure
|
onClick | Configure
|
Data Type Reference
Expand a card to inspect and copy the exact declaration. The code header identifies its repository file; follow imported or inherited types in the Implementation Source when you need the complete dependency chain. Required-field summaries cover fields declared directly in that type. Source-only helpers and inferred schema outputs describe the local implementation, not additional props you can pass to every component.
CarouselApi
DeclarationCarouselApiCarousel.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of CarouselApi before adapting it.CarouselOrientation
DeclarationCarouselOrientationCarousel.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of CarouselOrientation before adapting it.Carousel Props
8 declared fieldsCarouselPropsCarousel.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of CarouselProps before adapting it.CarouselAutoplayPause Props
1 declared fieldCarouselAutoplayPausePropsCarouselAutoplayPause.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of CarouselAutoplayPauseProps before adapting it.CarouselContent Props
1 declared fieldCarouselContentPropsCarouselContent.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of CarouselContentProps before adapting it.CarouselItem Props
1 declared fieldCarouselItemPropsCarouselItem.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of CarouselItemProps before adapting it.CarouselNext Props
1 declared fieldCarouselNextPropsCarouselNext.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of CarouselNextProps before adapting it.CarouselPrevious Props
1 declared fieldCarouselPreviousPropsCarouselPrevious.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of CarouselPreviousProps before adapting it.Accessibility
Carousel exposes a named carousel region when you provide label or aria-label; items use group/slide semantics. Previous and next controls have names. CarouselAutoplayPause supplies an explicit pause/resume action when you include it.
You have the pieces. Put them into one real interaction, keep its state in one place, and check the result with the content your application will actually show.
Connect the Foundation
Return to Choose and Compose Components to connect this reference to a working screen. Keep global CSS in one entrypoint and import only the components that screen needs.
Build the Surrounding Screen
Find a neighboring interaction in the Component Library, or start with a complete Block. Replace sample content and destinations before refining the layout; a local class change can stay with the composition.
Make the Result Hold Up
Use shared theme roles for changes that belong everywhere. Then review the whole journey: keyboard focus, long labels, narrow screens and a clear way to recover when something fails.
Keep a link to the source and note your intentional changes. Your next edit should begin with a clear decision, not another search.