<iframe src="https://www.googletagmanager.com/ns.html?id=GTM-5HGSQD2L" height="0" width="0" style="display:none;visibility:hidden" title="GTM"></iframe>

Carousel

A carousel allows multiple pieces of content to be browsed in a cyclical view.
styleKeys: carousel

Use Carousel...

  • In non-hero spots on the page, as a secondary element to showcase products or related content.
  • To display a series of content when space is limited.
  • To showcase a limited number of slides (2-4) to ensure user engagement and recall.

Don't use Carousel...

  • In a hero spot (a wide banner at the top of the page), as it leads to significantly lower engagement beyond the first slide.
  • To display SEO-relevant information, as search engines cannot index content that requires user interaction to view.

Default

The preview has been updated.

Skin

Full

Use skin="full" to indent the arrows on top of the slides and clip to the limits of the Carousel.

The preview has been updated.

Promo-bar

Use skin="promo-bar" to wrap a "promo bar" in a Carousel.

The preview has been updated.

Peek

Use peek with an infinitely-scrolling Carousel to make previous/next slides "peek" out from both edges, to show that there are more slides.

The preview has been updated.

Slides to show

Use slidesToShow to define how many slides are visible. Different values can be set for Responsive System breakpoints, for example {{ xs: 2, md: 6 }}. Decimal values are not supported and will be rounded down.

The preview has been updated.

Use slidesToShow with a decimal value to create a peek effect on the right edge.

The preview has been updated.

Grid Gutters

Use gridGutters to place gutters (gaps) between each slide. These gutters will match the width of the gutters on the layout Grid, so your slides will appear to be on the grid.

When using the gridGutters prop, slides should have rounded corners. StandardTile already has rounded corners, but for plain images or other content, wrap your slide contents in a Card component with fullBleed and overflow="hidden".

The preview has been updated.

Use a custom padding around each slide, using Space, to achieve a spacing different from the gridGutters: be aware that it will create a left and right inner indent, and the content won't look "on the grid" anymore.

The preview has been updated.

Arrows

Visibility

Use arrows={false} to hide the arrows.

Note: if the arrows are hidden, provide navigation through the Progress Indicator.

The preview has been updated.

Positioning

Arrows are centered vertically by default, using the total height of the Carousel.

When displaying content such as product tiles, arrows may appear visually misaligned.

  • Use arrowVerticalPosition to adjust the arrows' vertical positioning. e.g., arrowVerticalPosition="50px" vertically centers the arrows 50px from the top of the Carousel.
  • Use arrowVerticalOffset to shift arrows by a specified amount. e.g., arrowVerticalOffset="-40px" places the arrows 40px higher than the default.

The preview has been updated.

Finite

Use infinite={false} to provide a finite Carousel. By default, a Carousel will scroll infinitely. The arrow will be disabled at the end of a scroll.

The preview has been updated.

Progress Indicator

Dots

Use the progressIndicator to add dots that indicate the active slide and the total number of slides.

The preview has been updated.

Dots inset

Use progressIndicator="dots-inset" to make the dots overlap the content.

The preview has been updated.

Alignment

Use progressIndicatorAlignment="left" to make the dots left-aligned instead of centered.

The preview has been updated.

Accessibility

Labels

Carousels should have a text label that describes what the carousel contains. If a nearby element acts as that label, its id should be associated with the carousel using the aria-labelledby prop. Otherwise, provide an aria-label prop with a localized text value like "Recommended products".

Autoplay

Any carousel that auto-advances needs to have controls to let the user pause it. Until SWAN is able to add this feature, autoplay is not supported.

Implementation

Server-side rendering

Carousel uses JavaScript extensively for its layout, so when adjusting Carousel props by screen size, be mindful of the limitations of our Responsive System with SSR.

Placement

  • Use Carousels only when space constraints prevent displaying all items at once.
  • Avoid Carousels in hero spots, due to lower engagement beyond the first slide.

Content

  • Avoid placing SEO-relevant information in a Carousel, as search engines cannot index content requiring user interaction.
  • Limit slides to between two and four, as users are unlikely to recall or swipe past five slides.

Visual design

  • Keep controls inside the Carousel and ensure they are easily recognizable.

Tracking

Carousel is built with react-slick, which offers props such as beforeChange, afterChange, and onInit for tracking interactions.

The preview has been updated.

Props

SWAN's Carousel is built on top of the react-slick third-party component. See the Slick documentation for full prop descriptions.

CarouselSlide
This component is implemented using the <div /> as the root element. You can utilize the native attributes supported by <div /> tag. The ref is directly assigned to the root element, allowing you to access and manipulate it as needed.
See core props for additional props that can be applied to this component.
proptyperequireddefault
aria-roledescription
Localized label for assistive tech to identify this element as a "slide"
⚠️ Deprecated - This prop will be removed in favor of SWAN's i18n system. Please opt in to the i18n system for continued support.
stringfalse
slide
Carousel
This component is implemented using the <div /> as the root element. You can utilize the native attributes supported by <div /> tag. The ref is directly assigned to the root element, allowing you to access and manipulate it as needed.
See core props for additional props that can be applied to this component.
proptyperequireddefault
id
Set a unique id to the carousel
stringfalse
null
role
ARIA role for the Carousel component.
AriaRolefalse
region
aria-label
Provides an accessible label for the carousel container Defines a string value that labels the current element. @see aria-labelledby.
stringfalse
null
aria-labelledby
References of the element that labels the carousel container. Identifies the element (or elements) that labels the current element. @see aria-describedby.
stringfalse
null
aria-roledescription
Localized label for assistive tech to identify carousel container element as a "carousel."
⚠️ Deprecated - This prop will be removed in favor of SWAN's i18n system. Please opt in to the i18n system for continued support.
stringfalse
carousel
skin
The visual style of the Carousel.
"standard" | "promo-bar" | "full" | nullfalse
standard
slidesToShow
The number of slides to show at a time.
Responsive<number>false
1
progressIndicator
Specifies the way that slide-progress is indicated to the user.
"none" | "dots" | "dots-inset" | nullfalse
none
progressIndicatorAlignment
Specifies the alignment of the progress indicator.
"center" | "left" | nullfalse
center
peek
Whether to show a peek of the next slide.
boolean | nullfalse
false
gridGutters
Whether to place gutters between the slides that match the grid's gutters.
boolean | nullfalse
false
gridGuttersVariant
What kind of gutters to place between slides.
⚠️ Deprecated - This is deprecated without a replacement.
string | nullfalse
standard
arrowVerticalPosition
The vertical position of the arrows, as a CSS "top" property.
string | nullfalse
null
arrowVerticalOffset
The vertical offset of the arrows, relative to its CSS "top" property.
string | nullfalse
0px
accessibleTextForDots
Set accessible text for carousel dots.
⚠️ Deprecated - This prop will be removed in favor of SWAN's i18n system. Please opt in to the i18n system for continued support.
string[] | nullfalse
null
accessibleTextForPrevious
Set accessible text for previous button.
⚠️ Deprecated - This prop will be removed in favor of SWAN's i18n system. Please opt in to the i18n system for continued support.
stringfalse
null
accessibleTextForNext
Set accessible text for next button.
⚠️ Deprecated - This prop will be removed in favor of SWAN's i18n system. Please opt in to the i18n system for continued support.
stringfalse
null
currentSlide
The current slide of the carousel.
number | nullfalse
null
accessibleTextForVisibleSlides
Localized text to be used in the aria-live region that announces each slide change. Should utilize placeholders {start} and {totalSlides}, e.g. "Slide {start} of {totalSlides}". When multiple slides are visible at a time, include {end}, e.g. "Slides {start} through {end} of {totalSlides}"
⚠️ Deprecated - This prop will be removed in favor of SWAN's i18n system. Please opt in to the i18n system for continued support.
string | nullfalse
Slide {start} of {totalSlides}' | 'Slides {start} through {end} of {totalSlides}
accessibleTextForSlide
Localized text to be used as the aria-label for each slide. Should utilize placeholders {current} and {totalSlides}, e.g. "{current} of {totalSlides}".
⚠️ Deprecated - This prop will be removed in favor of SWAN's i18n system. Please opt in to the i18n system for continued support.
string | nullfalse
{current} of {totalSlides}

Internationalization

SWAN's Internationalization System allows SWAN components to render with fully translated and accessible text out-of-the-box. The following keys are provided to allow you to override the default translation.

Default TextKey
slide
Accessible description for a single item in a Carousel component, used for aria-roledescription, i.e. a Carousel slide
carousel-slide.aria-roledescription
Go to slide {{slideNumber}}
carousel.accessible-text-for-dot-button
Go to next slide
carousel.accessible-text-for-next-button
Go to previous slide
carousel.accessible-text-for-previous-button
{{current}} of {{totalSlides}}
carousel.accessible-text-for-slide
Slide {{start}} of {{totalSlides}}
carousel.accessible-text-for-visible-slides_one
Slides {{start}} to {{end}} of {{totalSlides}}
carousel.accessible-text-for-visible-slides_other
carousel
Accessible description for a Carousel component, used for aria-roledescription
carousel.aria-roledescription

Related