Migration Information

For teams migrating from the V1 to V2 component, please refer to the migration guide for changes to the component.

Component Guide

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.

SlidesPerView

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.

SlidesPerScroll

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.

Programatic slide navigation

The Carousel component offers three external ref functions to programatically navigate through it:

• goToPrevSlide to navigate to the previous slide.
• goToNextSlide to navigate to the next slide.
• goToSlide to navigate to a desired slide by passing the slide's index. Note: This function is zero-based index.

EmblaOverrides

Carousel uses the library 'embla-carousel-react'. For further customization, you can use prop emblaOverrides to pass in additional options. For more information, look here: https://www.embla-carousel.com/api/options/.

Note: We do not support all overrides. Teams who wish to do so may need further individual customization.

Carousel Props

Name	Type	Default	Required	Description
className	string	-	-	CSS class name to apply to each element within the component
css	Abyss.CSSProperties | Partial<Record<`abyss-${T}`, Abyss.CSSProperties>>	-	-	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	-	-	Suffix used to create a unique ID used for automated testing See Component Testing for more information
disableDefaultProviderProps	boolean	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 docs for more information
headingLevel	1 | 2 | 3 | 4 | 5 | 6	2	-	Heading level of the Carousel label
label	string	'Carousel'	-	The Carousel label
nextSlideOnClick	(() => void) | null	-	-	Callback function executed when the "Next slide" button is clicked
onViewAll	() => void	-	-	Callback function executed when the "View all" button is clicked
prevSlideOnClick	(() => void) | null	-	-	Callback function executed when the "Previous slide" button is clicked
slideIndexOnClick	((index: number) => void) | null	-	-	Callback function executed when a slide index button is clicked
slides	React.ReactNode[]	-	-	The Carousel slides; must be Slide components
slidesPerScroll	number	-	-	The number of slides to move per scroll action
slidesPerView	number	1	-	The number of slides to show in view at once
subText	string	-	-	The Carousel sub-text description

Below are the link(s) to the relevant GitHub type files:

Abyss.d.ts

Carousel.types.ts

Slide Props

Name	Type	Default	Required	Description
children	any	-	-	The Slide content
className	string	-	-	CSS class name to apply to each element within the component
css	Abyss.CSSProperties | Partial<Record<`abyss-${T}`, Abyss.CSSProperties>>	-	-	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	-	-	Suffix used to create a unique ID used for automated testing See Component Testing for more information
disableDefaultProviderProps	boolean	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.

Below are the link(s) to the relevant GitHub type files:

Slide.types.ts

CarouselHandle (External Ref) Props

Name	Type	Default	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-root	Carousel root element
.abyss-carousel-swiper-container	Swiper container
.abyss-carousel-slide-container	Carousel slide container
.abyss-carousel-heading	Text above the swiper container
.abyss-carousel-label	Label on the carousel
.abyss-carousel-subtext	Sub-text below the label
.abyss-carousel-view-all	"View all" link
.abyss-carousel-controls	Carousel controls
.abyss-carousel-nav-container-left	Left nav container
.abyss-carousel-nav-container-right	Right nav container
.abyss-carousel-pagination-container	Pagination button container
.abyss-carousel-bullet-container	Pagination bullet container
.abyss-carousel-pagination	Pagination buttons
.abyss-carousel-heading-wrapper	Wrapper for the carousel heading
.abyss-carousel-view-all-container	Container for the "View all" link

Slide Classes

Class Name	Description
.abyss-slide-container	Slide container element
.abyss-slide-card	Slide card 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 pattern, in particular, the Carousel with tabs for slide control.

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

Note: Click on the token row to copy the token to your clipboard.

Search tokens

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