Carousel
A swipeable slideshow with previous/next controls, indicators, looping and optional autoplay.
Attributes
| Name | Type | Default | Description |
|---|---|---|---|
index | number | 0 | Zero-based index of the slide at the start of the viewport. Reflected, and clamped to the reachable range. |
loop | boolean | false | Wrap previous/next around the ends instead of stopping there. |
autoplay | boolean | false | Advance to the next slide every interval milliseconds and show a play/pause control. |
mouse-drag | boolean | true | Let a mouse drag the track from slide to slide. Touch and trackpads scroll it natively either way; "false" turns it off. |
interval | number | 5000 | Milliseconds each slide stays on show while autoplay rotates. |
label | string | — | Accessible name of the carousel region. Defaults to "Carousel" in the nearest lang. |
previous-label | string | — | Accessible name of the previous-slide control. Defaults to "Previous slide" in the nearest lang. |
next-label | string | — | Accessible name of the next-slide control. Defaults to "Next slide" in the nearest lang. |
indicators-label | string | — | Accessible name of the indicator group. Defaults to "Choose slide" in the nearest lang. |
indicator-label-template | string | — | Accessible name of an indicator. Placeholders: {index} (1-based), {count}. Defaults to "Go to slide {index}" in the nearest lang. |
slide-label-template | string | — | Accessible name given to a slide without its own aria-label. Placeholders: {index} (1-based), {count}. Defaults to "{index} of {count}" in the nearest lang. |
play-label | string | — | Accessible name of the control that starts rotation. Defaults to "Start slide rotation" in the nearest lang. |
pause-label | string | — | Accessible name of the control that stops rotation. Defaults to "Stop slide rotation" in the nearest lang. |
Slots
| Name | Description |
|---|---|
(default) | The slides. Every child element is one slide. |
previous-icon | Icon of the previous-slide control. Defaults to a chevron. |
next-icon | Icon of the next-slide control. Defaults to a chevron. |
play-icon | Icon of the play control shown with autoplay while rotation is stopped. |
pause-icon | Icon of the pause control shown with autoplay while slides rotate. |
Events
| Name | Type | Description |
|---|---|---|
slide-change | CustomEvent<SlideChangeEventDetail> | Fired after the slide at the start of the viewport changes by a control, an indicator, the keyboard, a swipe, a drag, a click on a peeking slide, autoplay or a next()/previous()/goTo() call. Setting index does not fire it. Does not bubble. |
CSS parts
Shadow DOM styling hooks used with ::part(name). Prefer CSS custom properties when they cover the change.
| Name | Description |
|---|---|
carousel | The region that wraps the whole carousel. |
track | The scrolling row of slides. |
control | The previous and next buttons. |
previous | The previous-slide button. |
next | The next-slide button. |
indicators | The row of indicators, with the play/pause control when autoplay is set. |
indicator | One indicator button. |
rotation | The play/pause button shown with autoplay. |
CSS custom properties
Grouped by semantic target and state from --c2-<component>__<target>__<state>--<property>. Click a group to collapse it; click a name to copy it.
| Name | Type | Default | Description |
|---|---|---|---|
--c2-carousel--gap | pixel | 16px | Space between slides. |
--c2-carousel__slide--width | length | 100% | Width of one slide; 50% shows two at once, 85% lets the next one peek in. |
--c2-carousel__track--border-radius | border-radius | 8px | Rounding of the viewport the slides scroll through. |
--c2-carousel__track__focus--outline | outline | 2px solid rgba(2, 101, 220, 0.4) | |
--c2-carousel__track__focus--outline-offset | pixel | 2px | |
--c2-carousel__control--display | display | inline-flex | none hides the previous/next buttons. |
--c2-carousel__control--opacity | opacity | 1 | Opacity of the previous/next buttons while the pointer is off the carousel and focus is outside it; 0 shows them only on hover. Ignored on devices that cannot hover. |
--c2-carousel__control--transition-duration | time | 240ms | How long the previous/next buttons take to fade and slide in and out. |
--c2-carousel__control--size | pixel | 36px | |
--c2-carousel__control--inset | pixel | 12px | Distance from a control to the edge of the track. |
--c2-carousel__control--color | color | #18181b | |
--c2-carousel__control--background-color | color | #ffffff | |
--c2-carousel__control--border | border | 1px solid #e4e4e7 | |
--c2-carousel__control--border-radius | border-radius | 999px | |
--c2-carousel__control--box-shadow | box-shadow | 0 8px 24px rgba(24, 24, 27, 0.08) | |
--c2-carousel__control__opposite--opacity | opacity | 1 | Opacity of a control the pointer is not near while it hovers the carousel: with 0 only the edge zone under the pointer shows its button (previous on the left, next on the right) and the middle shows neither. A focused control always shows. |
--c2-carousel__control__zone--width | length | 20% | Width of the zone along each edge of the track that reveals that edge's control; a percentage is of the track width. Never narrower than the control and its inset. |
--c2-carousel__control__hidden--translate | pixel | 8px | How far towards its edge a hidden previous/next button sits; it slides in from there as it fades in. 0px only fades. |
--c2-carousel__control__hover--background-color | color | #f4f4f5 | |
--c2-carousel__control__focus--outline | outline | 2px solid rgba(2, 101, 220, 0.4) | |
--c2-carousel__control__focus--outline-offset | pixel | 2px | |
--c2-carousel__control__disabled--opacity | opacity | 0.38 | |
--c2-carousel__icon--size | pixel | 16px | |
--c2-carousel__rotation--color | color | #71717a | Colour of the play/pause control in the indicator row. |
--c2-carousel__rotation__hover--color | color | #18181b | |
--c2-carousel__indicators--display | display | flex | none hides the indicator row. |
--c2-carousel__indicators--gap | pixel | 4px | Space between indicators. |
--c2-carousel__indicators--margin-top | pixel | 8px | Space between the track and the indicator row. |
--c2-carousel__indicators--justify-content | justify-content | center | Where the indicators sit in the row. |
--c2-carousel__indicator--width | pixel | 8px | |
--c2-carousel__indicator--height | pixel | 8px | |
--c2-carousel__indicator--border-radius | border-radius | 999px | |
--c2-carousel__indicator--background-color | color | #a1a1aa | |
--c2-carousel__indicator--transition-duration | time | 200ms | |
--c2-carousel__indicator__hover--background-color | color | #71717a | |
--c2-carousel__indicator__selected--width | pixel | 24px | Width of the indicator of the current slide. |
--c2-carousel__indicator__selected--background-color | color | rgb(2, 101, 220) | |
--c2-carousel__indicator__focus--outline | outline | 2px solid rgba(2, 101, 220, 0.4) | |
Text and languages
The text the component shows, in English. It shows another language when the app adds one with addTranslations, under carousel, and the nearest lang asks for it; any message not translated stays in English. {0}, {1}… stand for the values a message carries. Languages guide.
| Key | English | Values |
|---|---|---|
label | Carousel | — |
carousel | carousel | — |
slide | slide | — |
previous | Previous slide | — |
next | Next slide | — |
indicators | Choose slide | — |
goTo | Go to slide {0} | {0} index {1} _count |
slideLabel | {0} of {1} | {0} index {1} count |
play | Start slide rotation | — |
pause | Stop slide rotation | — |