Skip to content
Kimenpre-v1documentation home
Color scheme

ki-carousel

Use a carousel for related media, feature highlights or onboarding. Give the region a short, meaningful label and write each slide as a ki-carousel-item.

Theme for this example
Color scheme for this example
Guarded catalogBuild from approved components. Themesonmars and Material 3. AdaptersConnect surfaces to your app.
<ki-carousel label="Kimen highlights" layout="multi-browse" loop>
<ki-carousel-item><strong>Guarded catalog</strong><span>Build from approved components.</span></ki-carousel-item>
<ki-carousel-item><strong>Themes</strong><span>onmars and Material 3.</span></ki-carousel-item>
<ki-carousel-item><strong>Adapters</strong><span>Connect surfaces to your app.</span></ki-carousel-item>
</ki-carousel>

Layout and movement

  • single shows one item by default. Set slides-per-view to show multiple full items and slides-per-move to advance in steps. The final position keeps a full view.
  • multi-browse shows one large item with medium and small previews.
  • hero shows one large item with a small preview.
  • uncontained reveals the next item at the edge of the viewport.
  • full-screen snaps vertically. Set --ki-carousel-full-screen-block-size to the desired feed height.

For reduced-size previews, give the item decorative media in the preview slot and keep any links and text in its default slot.

Call next(), previous(), or goTo(index), or set current. The index starts at 1 and reports the leading item. Listen for ki-slide-change to receive the new index in event.detail.index.

Accessibility

The viewport accepts arrow keys, Home and End. Previous and Next also work with Space and Enter. Slide content stays available while fully visible. Partially shown previews are inert. Manual changes announce the new position.

Rotation starts only with a positive autoplay interval in milliseconds. Hover suspends rotation. Focus stops it until the reader presses Play. Reduced motion keeps rotation off and slide movement immediate. Localize the control and slide labels with the props in the API reference.

API reference

When to use: show a short set of related highlights, onboarding steps or media panels. Give the carousel a meaningful label and supply one ki-carousel-item per slide.

When not to use: hide essential content behind rotation, replace ordinary page navigation, or present slides that readers need to compare side by side at the same time.

AttributePropertyTypeDefaultDescription
autoplayautoplaynumber | undefined–Rotation interval in milliseconds. Omitting it leaves rotation off.
carousel-role-descriptioncarouselRoleDescriptionstring'carousel'Accessible role description of the region.
currentcurrentnumber1One-based leading slide. Setting it moves the carousel and clamps the index to the available leading positions.
labellabelstring–Required accessible name of the carousel region.
layoutlayout"full-screen" | "hero" | "multi-browse" | "single" | "uncontained"'single'Item arrangement. Full-screen uses a vertical, full-viewport slide.
looploopbooleanfalseWhether navigating past one endpoint wraps to the other.
navigationnavigationbooleantrueWhether to show the Previous and Next buttons. The viewport stays keyboard-operable.
next-labelnextLabelstring'Next slide'Accessible label of the Next button.
paginationpaginationbooleantrueWhether to show the noninteractive slide position indicator.
pause-labelpauseLabelstring'Pause'Visible and accessible label of the Pause button.
play-labelplayLabelstring'Play'Visible and accessible label of the Play button.
position-labelpositionLabelstring'Slide position'Accessible label of the position indicator.
previous-labelpreviousLabelstring'Previous slide'Accessible label of the Previous button.
slide-labelslideLabelstring'{index} of {count}'Spoken slide name and announcement. Use {index} and {count} as placeholders.
slide-role-descriptionslideRoleDescriptionstring'slide'Accessible role description of each slide group.
slides-per-moveslidesPerMovenumber1Number of positions advanced by Previous, Next and automatic rotation.
slides-per-viewslidesPerViewnumber1Number of slides visible together in the single layout. Material 3 layouts determine their own item widths.
EventDetail typeDescription
ki-slide-changeCustomEvent<CarouselSlideChangeDetail>Reports the one-based index when the leading slide changes.
MethodDescription
goTo(index: number) => Promise<void>Moves to the requested one-based leading position within the available range.
next() => Promise<void>Advances by slidesPerMove.
previous() => Promise<void>Moves back by slidesPerMove.
SlotDescription
(default)Direct ki-carousel-item children in reading order.
PartDescription
announcementVisually hidden live region for manual changes.
controlsRow containing slide position and navigation.
nextNext slide button.
positionPosition indicator and optional numeric position.
previousPrevious slide button.
rotationPlay or Pause button when automatic rotation is configured.
viewportScroll-snap viewport and its keyboard focus outline.

The public styling contract of ki-carousel: reassign these tokens at :root or on a subtree — never override internals.

TokenDescription
--ki-carousel-control-backdrop-filterComplete optional backdrop filter for the carousel controls.
--ki-carousel-control-bgSurface of the carousel navigation and rotation controls.
--ki-carousel-control-bg-imageOptional image layered over the carousel control background color.
--ki-carousel-control-borderVisible control boundary against the surrounding surface.
--ki-carousel-control-fgText and glyph ink against the carousel control surface.
--ki-carousel-control-gapSpacing between carousel controls.
--ki-carousel-control-icon-sizeGlyph size in the carousel navigation controls.
--ki-carousel-control-radiusCorner radius of the carousel controls.
--ki-carousel-control-shadowResting elevation of the carousel controls.
--ki-carousel-control-sizeResting carousel control size before applying the density target floor.
--ki-carousel-full-screen-block-sizeBlock size of the vertical carousel viewport.
--ki-carousel-gapGap between carousel slides and between the viewport and the controls.
--ki-carousel-preview-min-inline-sizeMinimum inline size of a decorative carousel preview when space permits.
--ki-carousel-radiusCorner radius shared by the carousel viewport and slide surfaces.
--ki-control-border-widthStroke width of the boundary of a compact control.
--ki-density-space-scaleMultiplies every scaled container padding and gap (card, dialog, alert, list, list item, select listbox, tab panel, tooltip).
--ki-density-target-minThe smallest pointer target any density may produce: 24 x 24 CSS px by default and in compact (WCAG 2.5.8 AA), 44 x 44 in touch (WCAG 2.5.5). It floors a shrinking control but never lifts what a control paints: a control painted smaller extends its target to it, invisibly; rows and tabs grow to it (spec 045 A1).
--ki-focus-ring-colorColour of the keyboard focus ring every focusable component draws: 3:1 or more against the page in every theme and scheme.
--ki-focus-ring-offsetGap between a focusable component and its keyboard focus ring.
--ki-focus-ring-widthThickness of the keyboard focus ring every focusable component draws (its outline). One token instead of one per component, so a mode or a theme changes every ring at once.
--ki-typography-family-bodysemantic font family for typography family body.

When to use: supply a single slide to a ki-carousel. Put the full slide in the default slot and optional decorative preview media in the preview slot.

When not to use: present a standalone card or a layout container outside a carousel.

SlotDescription
(default)The full slide content, including any links and controls.
previewDecorative, noninteractive media shown when the item is a reduced preview.
PartDescription
contentSurface that holds the full slide.
previewDecorative surface used in small or partly shown previews.

The public styling contract of ki-carousel-item: reassign these tokens at :root or on a subtree — never override internals.

TokenDescription
--ki-carousel-item-backdrop-filterComplete optional backdrop filter for the slide surface.
--ki-carousel-item-bgSurface for carousel slide content and its decorative preview.
--ki-carousel-item-bg-imageOptional image layered over the slide background color.
--ki-carousel-item-fgText on the carousel slide surface.
--ki-carousel-item-min-block-sizeMinimum block size of a full slide.
--ki-carousel-item-paddingInset of full slide content.
--ki-carousel-radiusCorner radius shared by the carousel viewport and slide surfaces.
--ki-control-border-widthStroke width of the boundary of a compact control.
--ki-density-space-scaleMultiplies every scaled container padding and gap (card, dialog, alert, list, list item, select listbox, tab panel, tooltip).
--ki-typography-family-bodysemantic font family for typography family body.

Workshop

Open Carousel in Storybook