import { Carousel, Slide } from '@uhg-abyss/web/ui/Carousel';Usage
Label
Use the label prop to provide the title of the carousel. This is required for accessibility and, if no label is provided, will default to 'Carousel'.
By default, label is displayed as an 'h2'. This can be customized with the headingLevel prop.
SubText
Use the optional prop subText to provide more contextual information about the carousel.
View all
Use the optional onViewAll prop to provide a custom method to showcase all the carousel slides. If provided, onViewAll will be assigned to the onClick event of the "View all" link.
The example below demonstrates how to use the onViewAll prop to display all the slides using the ModalDialog component with size="fullscreen".
Slides
To define a slide of the carousel, wrap your contents in our Slide sub-component. Use the slides prop to pass an array of Slides to the carousel.
Slides per view
Use slidesPerView to change how many full slides are viewed at one time. Width of the slides is dynamically adjusted to properly fit the number of slidesPerView, while always providing a 24px peek of the next slide. This is to indicate that there are more slides to view. The default is set to 1.
Slides per scroll
Use slidesPerScroll to define how far the carousel should move per scroll. If no value is provided, it will default to match the value of slidesPerView.
Programmatic slide navigation
The Carousel component offers three external ref functions to programmatically navigate through it:
goToPrevSlideto navigate to the previous slide.goToNextSlideto navigate to the next slide.goToSlideto navigate to a desired slide by passing the slide's index (zero-based).
Embla overrides
Carousel uses the 'embla-carousel-react' library. For further customization, you can use the emblaOverrides prop to provide additional options. For more information, see the Embla documentationopens in a new window.
We do not support all overrides. Teams who wish to do so may need further individual customization.
Carousel Props
| Name | Type | Default | A11y | Description |
|---|---|---|---|---|
className | string | undefined | CSS class name to apply to each element within the component | ||
css | CSSProperties | Partial<Record<"abyss-carousel-label" | "abyss-carousel-heading" | "abyss-carousel-root" | "abyss-carousel-subtext" | "abyss-carousel-swiper-container" | ... 9 more ... | "abyss-carousel-view-all-container", CSSProperties>> | undefined | Object containing CSS styling to apply; uses the classes listed in the "Integration" tab of the component's documentation See CSS Prop Styling for more information | ||
data-testid | string | undefined | Suffix used to create a unique ID used for automated testing See Component Testing for more information | ||
disableDefaultProviderProps | boolean | undefined | false | If set to true, the component will not use the DefaultPropsProvider values. If you aren’t using the DefaultPropsProvider, this prop can be ignored. | |
emblaOverrides | Partial<OptionsType> | undefined | Embla Carousel overrides See the Embla Carousel options docsopens in a new window for more information | ||
headingLevel | 1 | 2 | 3 | 4 | 5 | 6 | undefined | 2 | Heading level of the Carousel label | |
hiddenFrom | Breakpoint | undefined | When defined, the component is hidden once the screen width reaches the specified breakpoint. | ||
label | string | undefined | 'Carousel' | The Carousel label, rendered as a semantic heading so screen reader users can identify and navigate to the carousel. | |
nextSlideOnClick | (() => void) | null | undefined | Callback function executed when the "Next slide" button is clicked | ||
onViewAll | (() => void) | undefined | Callback function executed when the "View all" button is clicked | ||
prevSlideOnClick | (() => void) | null | undefined | Callback function executed when the "Previous slide" button is clicked | ||
slideIndexOnClick | ((index: number) => void) | null | undefined | Callback function executed when a slide index button is clicked | ||
slides | ReactNode[] | undefined | The Carousel slides; must be Slide components | ||
slidesPerScroll | number | undefined | The number of slides to move per scroll action | ||
slidesPerView | number | undefined | 1 | The number of slides to show in view at once | |
slotProps | Partial<Record<ToSlotKey<{ root: LeafSlotDef<"section", undefined>; swiperContainer: LeafSlotDef<"div", undefined>; slideContainer: LeafSlotDef<"div", undefined>; ... 11 more ...; viewAllContainer: LeafSlotDef<...>; }, "carousel">, SlotPropsLeafValue>> | undefined | Slot props for overriding internal elements | ||
subText | string | undefined | The Carousel sub-text description | ||
visibleFrom | Breakpoint | undefined | When defined, the component is hidden until the screen width reaches the specified breakpoint. |
Slide Props
| Name | Type | Default | A11y | Description |
|---|---|---|---|---|
children | any | The Slide content. Headings within a slide must nest under the Carousel's label heading. | ||
className | string | undefined | CSS class name to apply to each element within the component | ||
css | CSSProperties | Partial<Record<"abyss-slide-container" | "abyss-slide-card", CSSProperties>> | undefined | Object containing CSS styling to apply; uses the classes listed in the "Integration" tab of the component's documentation See CSS Prop Styling for more information | ||
data-testid | string | undefined | Suffix used to create a unique ID used for automated testing See Component Testing for more information | ||
disableDefaultProviderProps | boolean | undefined | false | If set to true, the component will not use the DefaultPropsProvider values. If you aren’t using the DefaultPropsProvider, this prop can be ignored. | |
hiddenFrom | Breakpoint | undefined | When defined, the component is hidden once the screen width reaches the specified breakpoint. | ||
slotProps | Partial<Record<string, SlotPropsValue<string>>> | undefined | Props to pass to individual internal slots of the component, keyed by the slot name (e.g. 'button-root'). Supports className, css, style, aria-*, data-*, data-testid, and nested slotProps for child Abyss components. See slotProps for more information | ||
visibleFrom | Breakpoint | undefined | When defined, the component is hidden until the screen width reaches the specified breakpoint. |
CarouselHandle (External Ref) Props
| Name | Type | Required | Description |
|---|---|---|---|
goToNextSlide | () => void | Scroll to the next slide | |
goToPrevSlide | () => void | Scroll to the previous slide | |
goToSlide | (index: number) => void | Scroll to a specific slide |
Carousel Classes
| Class Name | Description |
|---|---|
| .abyss-carousel-bullet-container | Pagination bullet container |
| .abyss-carousel-controls | Carousel controls |
| .abyss-carousel-heading | Text above the swiper container |
| .abyss-carousel-heading-wrapper | Wrapper for the carousel heading |
| .abyss-carousel-label | Label on the carousel |
| .abyss-carousel-nav-container-left | Left nav container |
| .abyss-carousel-nav-container-right | Right nav container |
| .abyss-carousel-pagination | Pagination buttons |
| .abyss-carousel-pagination-container | Pagination button container |
| .abyss-carousel-root | Carousel root element |
| .abyss-carousel-slide-container | Carousel slide container |
| .abyss-carousel-subtext | Sub-text below the label |
| .abyss-carousel-swiper-container | Swiper container |
| .abyss-carousel-view-all | "View all" link |
| .abyss-carousel-view-all-container | Container for the "View all" link |
Slide Classes
| Class Name | Description |
|---|---|
| .abyss-slide-card | Slide card element |
| .abyss-slide-container | Slide container element |
A carousel presents a set of items, referred to as slides, by sequentially displaying a subset of one or more slides. Typically, one slide is displayed at a time, and users can activate a next or previous slide control that hides the current slide and "rotates" the next or previous slide into view. In some implementations, rotation automatically starts when the page loads, and it may also automatically stop once all the slides have been displayed. While a slide may contain any type of content, image carousels where each slide contains nothing more than a single image are common.
Adheres to the Carousel WAI-ARIA design patternopens in a new window, in particular, the Carousel with tabs for slide controlopens in a new window.
Keyboard Interactions
| Key | Description |
|---|---|
| Tab and Shift + Tab | Move focus through the interactive elements of the carousel as specified by the page tab sequence. |
| Right Arrow | Moves focus to the next tab. Shows the slide associated with the newly focused tab. |
| Left Arrow | Moves focus to the previous tab. Shows the slide associated with the newly focused tab. |
| Home | Moves focus to the first tab. Shows the slide associated with the newly focused tab. |
| End | Moves focus to the last tab. Shows the slide associated with the newly focused tab. |
| Button | Button elements implement the keyboard interaction defined in the Button Pattern. Note: Activating the rotation control, next slide, and previous slide do not move focus, so users may easily repetitively activate them as many times as desired. |
| Rotation Control | If present, the rotation control is the first element in the Tab sequence inside the carousel. It is essential that it precede the rotating content so it can be easily located. |
Component Tokens
Click on the token row to copy the token to your clipboard.
Carousel Tokens
| Token Name | Value | |
|---|---|---|
| carousel.color.text.heading | #002677 | |
| carousel.color.text.paragraph | #4B4D4F | |
| carousel.color.icon.bullets.disabled | #7D7F81 | |
| carousel.color.icon.bullets.rest | #196ECF | |
| carousel.color.icon.bullets.hover | #004BA0 | |
| carousel.color.icon.bullets.active | #002677 | |
| carousel.spacing.gap.vertical.container | 16px | |
| carousel.spacing.gap.horizontal.cards.mobile | 16px | |
| carousel.spacing.gap.horizontal.cards.web | 24px | |
| carousel.spacing.gap.horizontal.heading | 8px | |
| carousel.spacing.gap.horizontal.controls | 8px |