A NSW Government website
Design System v3.18.3

Card carousel

A card carousel displays multiple related cards horizontally, allowing users to swipe or navigate through the content.

Usage

The card carousel component displays four or more related cards within a limited space, allowing users to scroll through them via arrows, navigation buttons, or swiping gestures on a touchscreen.

Use a card carousel component:

  • when you have limited screen space but need to display multiple cards with related content.
  • with a clear and relevant title, to help users understand the content or purpose better.
  • to display feature articles, blog posts, news updates or any sequential content, allowing users to browse through the latest updates easily.

When to avoid

It's essential to implement card carousels thoughtfully to ensure they genuinely enhance user experience.

Do not:

  • use multiple card carousels on one page. Use carousels sparingly and strategically. Overuse can lead to banner blindness or user frustration.
  • use for unrelated items. The content in the carousel should be related in some way. This helps users to find related and relevant content.
  • mix different types of cards. Consistency helps users anticipate the content and interactions.
  • overwhelm users with too many cards in the carousel. Ideally, limit the number of cards to no more than 9 to prevent information overload.
  • use if your cards contain important information, as users may overlook it if they do not engage with the carousel.

Ensure that the content displayed in the carousel is relevant, engaging, and adds value to the user experience.

How this component works

Options

You can edit the following data attributes to customize the carousel behavior:

  • drag: to disable drag on touch devices, add a data-drag="off" to the js-carousel element (default is on);
  • infinite loop: to enable infinite loop, add a data-loop="on" to the js-carousel element (default is off);
  • carousel navigation: to disable the carousel dots navigation, add a data-navigation="off" (default is on); this option is only available when not using data-loop="on".

Carousel Item Number

The number of items visible in a carousel cycle is determined based on the width of the .nsw-carousel__item as defined in the card-carousel.scss file. To modify this value, you can change the --carousel-item-auto-size CSS variable (default is 300px).

Carousel Dots Navigation

You can customize the carousel navigation using the following data attributes:

  • data-navigation-class: pass a list of custom classes to be added to the navigation element (default is nsw-carousel__navigation);
  • data-navigation-item-class: pass a custom class for the navigation list items (default is nsw-carousel__nav-item). When an item is selected, the class {navigation-item-class}--selected is added to that element (e.g., if data-navigation-item-class='nsw-carousel__navigation-item', the selected class will be nsw-carousel__navigation-item--selected);
  • data-navigation-pagination: set it to 'on' to use the carousel navigation as a pagination element.

Center Items

If the carousel items number is smaller than the number of visible items, and you want them to be centered in the viewport, add a data-justify-content="on" to the .nsw-carousel item. By default items will be aligned to the left.

Accessibility

All components are responsive and designed to comply with WCAG 2.2 AA accessibility standards. Full compliance depends on using and configuring the components correctly.

The card carousel conforms to the W3C Carousel Design Pattern and includes a Live Region that allows screen readers to read content whenever carousel slides change.

Keyboard Interactions and focus

  • Tab key moves focus through interactive elements in the carousel. Rotation control, previous slide, and next slide buttons precede the slide content in the Tab sequence.
  • Shift + Tab keys moves focus to the previous focusable element
  • Enter , Left Arrow and Right Arrow keys display next or previous slide in the carousel.

Screen Reader Announcement of Slide Changes

The card carousel slide content is included in a live region. This makes it easier for screen reader users to scan through the carousel slides. When screen reader users activate the next or previous slide button, the new slide content is announced, giving users immediate feedback that helps them determine whether or not to interact with the content.

ARIA attributes

  • The card carousel container has the role property set to group with the property aria-roledescription set to 'carousel'.
  • Each card container has role group with the property aria-roledescription set to slide.
  • The next slide control, and previous slide control are native button elements.

The card carousel component is best viewed in new window.

Pagination