ki-carousel
@kimen/elements/ki-carousel- Source
- Agent reference
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.
<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
singleshows one item by default. Setslides-per-viewto show multiple full items andslides-per-moveto advance in steps. The final position keeps a full view.multi-browseshows one large item with medium and small previews.heroshows one large item with a small preview.uncontainedreveals the next item at the edge of the viewport.full-screensnaps vertically. Set--ki-carousel-full-screen-block-sizeto 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.
Properties & attributes
| Attribute | Property | Type | Default | Description |
|---|---|---|---|---|
autoplay | autoplay | number | undefined | – | Rotation interval in milliseconds. Omitting it leaves rotation off. |
carousel-role-description | carouselRoleDescription | string | 'carousel' | Accessible role description of the region. |
current | current | number | 1 | One-based leading slide. Setting it moves the carousel and clamps the index to the available leading positions. |
label | label | string | – | Required accessible name of the carousel region. |
layout | layout | "full-screen" | "hero" | "multi-browse" | "single" | "uncontained" | 'single' | Item arrangement. Full-screen uses a vertical, full-viewport slide. |
loop | loop | boolean | false | Whether navigating past one endpoint wraps to the other. |
navigation | navigation | boolean | true | Whether to show the Previous and Next buttons. The viewport stays keyboard-operable. |
next-label | nextLabel | string | 'Next slide' | Accessible label of the Next button. |
pagination | pagination | boolean | true | Whether to show the noninteractive slide position indicator. |
pause-label | pauseLabel | string | 'Pause' | Visible and accessible label of the Pause button. |
play-label | playLabel | string | 'Play' | Visible and accessible label of the Play button. |
position-label | positionLabel | string | 'Slide position' | Accessible label of the position indicator. |
previous-label | previousLabel | string | 'Previous slide' | Accessible label of the Previous button. |
slide-label | slideLabel | string | '{index} of {count}' | Spoken slide name and announcement. Use {index} and {count} as placeholders. |
slide-role-description | slideRoleDescription | string | 'slide' | Accessible role description of each slide group. |
slides-per-move | slidesPerMove | number | 1 | Number of positions advanced by Previous, Next and automatic rotation. |
slides-per-view | slidesPerView | number | 1 | Number of slides visible together in the single layout. Material 3 layouts determine their own item widths. |
Events
| Event | Detail type | Description |
|---|---|---|
ki-slide-change | CustomEvent<CarouselSlideChangeDetail> | Reports the one-based index when the leading slide changes. |
Methods
| Method | Description |
|---|---|
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. |
Slots
| Slot | Description |
|---|---|
| (default) | Direct ki-carousel-item children in reading order. |
CSS parts
| Part | Description |
|---|---|
announcement | Visually hidden live region for manual changes. |
controls | Row containing slide position and navigation. |
next | Next slide button. |
position | Position indicator and optional numeric position. |
previous | Previous slide button. |
rotation | Play or Pause button when automatic rotation is configured. |
viewport | Scroll-snap viewport and its keyboard focus outline. |
CSS custom properties
The public styling contract of ki-carousel: reassign these tokens at :root or on a subtree — never override internals.
| Token | Description |
|---|---|
--ki-carousel-control-backdrop-filter | Complete optional backdrop filter for the carousel controls. |
--ki-carousel-control-bg | Surface of the carousel navigation and rotation controls. |
--ki-carousel-control-bg-image | Optional image layered over the carousel control background color. |
--ki-carousel-control-border | Visible control boundary against the surrounding surface. |
--ki-carousel-control-fg | Text and glyph ink against the carousel control surface. |
--ki-carousel-control-gap | Spacing between carousel controls. |
--ki-carousel-control-icon-size | Glyph size in the carousel navigation controls. |
--ki-carousel-control-radius | Corner radius of the carousel controls. |
--ki-carousel-control-shadow | Resting elevation of the carousel controls. |
--ki-carousel-control-size | Resting carousel control size before applying the density target floor. |
--ki-carousel-full-screen-block-size | Block size of the vertical carousel viewport. |
--ki-carousel-gap | Gap between carousel slides and between the viewport and the controls. |
--ki-carousel-preview-min-inline-size | Minimum inline size of a decorative carousel preview when space permits. |
--ki-carousel-radius | Corner radius shared by the carousel viewport and slide surfaces. |
--ki-control-border-width | Stroke width of the boundary of a compact control. |
--ki-density-space-scale | Multiplies every scaled container padding and gap (card, dialog, alert, list, list item, select listbox, tab panel, tooltip). |
--ki-density-target-min | The 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-color | Colour of the keyboard focus ring every focusable component draws: 3:1 or more against the page in every theme and scheme. |
--ki-focus-ring-offset | Gap between a focusable component and its keyboard focus ring. |
--ki-focus-ring-width | Thickness 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-body | semantic 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.
Slots
| Slot | Description |
|---|---|
| (default) | The full slide content, including any links and controls. |
preview | Decorative, noninteractive media shown when the item is a reduced preview. |
CSS parts
| Part | Description |
|---|---|
content | Surface that holds the full slide. |
preview | Decorative surface used in small or partly shown previews. |
CSS custom properties
The public styling contract of ki-carousel-item: reassign these tokens at :root or on a subtree — never override internals.
| Token | Description |
|---|---|
--ki-carousel-item-backdrop-filter | Complete optional backdrop filter for the slide surface. |
--ki-carousel-item-bg | Surface for carousel slide content and its decorative preview. |
--ki-carousel-item-bg-image | Optional image layered over the slide background color. |
--ki-carousel-item-fg | Text on the carousel slide surface. |
--ki-carousel-item-min-block-size | Minimum block size of a full slide. |
--ki-carousel-item-padding | Inset of full slide content. |
--ki-carousel-radius | Corner radius shared by the carousel viewport and slide surfaces. |
--ki-control-border-width | Stroke width of the boundary of a compact control. |
--ki-density-space-scale | Multiplies every scaled container padding and gap (card, dialog, alert, list, list item, select listbox, tab panel, tooltip). |
--ki-typography-family-body | semantic font family for typography family body. |