Carousel is deprecated in SWAN v3.25.0.
Use AdaptiveCarousel instead, which has improved performance and increased consistency for customers. See Deprecation for more information.
Carousel is only available in the React API for SWAN.
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
accessibleTextForPrevious, accessibleTextForNext, accessibleTextForDots, accessibleTextForVisibleSlides, accessibleTextForSlide and aria-roledescription are deprecated in SWAN 3.24. These prop will be removed in favor of SWAN's i18n system. Please opt in to the i18n system and remove these prop.
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.
Note: the peek feature expects that you are using a Carousel with infinite scrolling. Setting the infinite prop to false will break the Carousel if peek is also true. If you need a Carousel that is finite, but also shows a peek of adjacent slides, set slidesToShow to a non-integer value such as 1.2; see below.
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
gridGuttersVariant is deprecated in SWAN v3.14
As it is rarely used, it has been deprecated to improve consistency for customers and to maintain consistency with GridContainer and reduce UX debt.
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
arrowVerticalPositionto adjust the arrows' vertical positioning. e.g.,arrowVerticalPosition="50px"vertically centers the arrows 50px from the top of the Carousel. - Use
arrowVerticalOffsetto 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.
When using this option, you must provide the prop accessibleTextForDots to the Carousel.
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 value like "Recommended Products".
Role Descriptions
If you’re not using SWAN’s i18n system, all carousels must include an aria-roledescription prop with a localized value of "carousel" to correctly inform assistive technologies about the component’s behavior.
Similarly, each slide must have an aria-roledescription with a localized value of "slide".
Announcements
If you’re not using SWAN’s i18n system, assistive technology needs to be notified when the visible slides of a carousel have changed, and what slides those are. All carousels require a localized value for accessibleTextForVisibleSlides. It must contain a localize value of the string "Slide {start} of {totalSlides}" when only one slide is visible, and “Slides {start} through {end} of {totalSlides}“ when more than one slide is visible. Be sure to use those exact placeholders, the library will replace them with the appropriate numbers.”
Assistive technology needs to be able to distinguish each slide from one another. All carousels require a localized value for accessibleTextForSlide. It must contain a localized value of the string “{current} of {totalSlides}”. Be sure to use those exact placeholders, the library will replace them with the appropriate numbers.
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.
| prop | type | required | description | default |
|---|---|---|---|---|
| aria-roledescription | string | false | ⚠️ Deprecated - This prop will be removed in favor of SWAN's i18n system. Please opt in to the i18n system for continued support.
Localized label for assistive tech to identify this element as a "slide" | 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.
| prop | type | required | description | default |
|---|---|---|---|---|
| id | string | false | Set a unique id to the carousel | null |
| role | AriaRole | false | ARIA role for the Carousel component. | region |
| aria-label | string | false | Provides an accessible label for the carousel container
Defines a string value that labels the current element.
@see aria-labelledby. | null |
| aria-labelledby | string | false | References of the element that labels the carousel container.
Identifies the element (or elements) that labels the current element.
@see aria-describedby. | null |
| aria-roledescription | string | false | ⚠️ Deprecated - This prop will be removed in favor of SWAN's i18n system. Please opt in to the i18n system for continued support.
Localized label for assistive tech to identify carousel container element as a "carousel." | carousel |
| skin | "standard" | "promo-bar" | "full" | null | false | The visual style of the Carousel.
One of: "standard", "full", "promo-bar". | standard |
| slidesToShow | Responsive<number> | false | The number of slides to show at a time. | 1 |
| progressIndicator | "none" | "dots" | "dots-inset" | null | false | Specifies the way that slide-progress is indicated to the user.
One of: "none", "dots", "dots-inset". | none |
| progressIndicatorAlignment | "center" | "left" | null | false | Specifies the alignment of the progress indicator.
One of: "left", "center". | center |
| peek | boolean | null | false | Whether to show a peek of the next slide. | false |
| gridGutters | boolean | null | false | Whether to place gutters between the slides that match the grid's gutters. | false |
| gridGuttersVariant | string | null | false | ⚠️ Deprecated - This is deprecated without a replacement.
What kind of gutters to place between slides. | standard |
| arrowVerticalPosition | string | null | false | The vertical position of the arrows, as a CSS "top" property. | null |
| arrowVerticalOffset | string | null | false | The vertical offset of the arrows, relative to its CSS "top" property. | 0px |
| accessibleTextForDots | string[] | null | false | ⚠️ Deprecated - This prop will be removed in favor of SWAN's i18n system. Please opt in to the i18n system for continued support.
Set accessible text for carousel dots. | null |
| accessibleTextForPrevious | string | false | ⚠️ Deprecated - This prop will be removed in favor of SWAN's i18n system. Please opt in to the i18n system for continued support.
Set accessible text for previous button. | null |
| accessibleTextForNext | string | false | ⚠️ Deprecated - This prop will be removed in favor of SWAN's i18n system. Please opt in to the i18n system for continued support.
Set accessible text for next button. | null |
| currentSlide | number | null | false | The current slide of the carousel. | null |
| accessibleTextForVisibleSlides | string | null | false | ⚠️ Deprecated - This prop will be removed in favor of SWAN's i18n system. Please opt in to the i18n system for continued support.
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}" | Slide {start} of {totalSlides}' | 'Slides {start} through {end} of {totalSlides} |
| accessibleTextForSlide | string | null | false | ⚠️ Deprecated - This prop will be removed in favor of SWAN's i18n system. Please opt in to the i18n system for continued support.
Localized text to be used as the aria-label for each slide.
Should utilize placeholders {current} and {totalSlides}, e.g. "{current} of {totalSlides}". | {current} of {totalSlides} |
How does Carousel meet your needs?
Related