Carousel

Carousel facilitates the display of and navigation through a set of related items. Carousel can be configured to support a variety of workflows and use cases across the interface.

Overview

Carousel, combined with slotted Carousel Items, provides a mechanism for displaying a set of related content items. It is often used to contextually display related onboarding tips, or display messaging, media, or other related content.

Usage

  • Onboarding workflows
  • Contextual tip experiences
  • Showcasing media, graphics, or imagery
  • Facilitating casual content browsing experiences

Sample

Best practices

As Carousels support a variety of use cases, it is important to consider the context within which the Carousel will be used and select a combination of properties that best suit the experience.

A common use case for Carousels is to provide contextual onboarding or introductory tips to a user. This may be presented within a fleeting component, like a Dialog or Popover, or displayed in a static way - such as placing the Carousel within a Block or Panel.

Carousels can also be used as interactive displays to showcase rich media or graphical content. In these cases, the Carousel Item may contain a full-size background image and text-based content. This may be useful to show associated articles, detail pages, or other content that is related to the current context.

Carousel Items can contain any slotted content; components such as Card and Notice can be used alongside text, images, or other custom content as needed.

Recommendations

Carousel is intended to be used to display a set of Carousel Items containing related content. Because only one Carousel Item is displayed at a time, it is important to ensure that the contents of each Carousel Item are not critical or essential. Avoid placing configurable controls or form elements such as inputs, or other controls that may affect the user interface within a Carousel Item. If the content within a Carousel Item is crucial to a user workflow, consider using a different component or layout to display the content.

Do use Carousel to display multiple Carousel Items containing related content.
Do ensure content within each Carousel Item is non-critical.
Do ensure a limited number of Carousel Items are used.
Avoid using Carousel for crucial or important content.
Avoid using an excessive amount of Carousel Items within Carousel.
Avoid placing configurable controls or form elements - such as inputs - within a Carousel Item.

By default, the height of the Carousel is determined by that of the currently displayed Carousel Item. As a result, the height of the Carousel may change as the user navigates through the Carousel Items. Try to ensure that the content in each Carousel Item is of a similar length and structure to lessen the occurrence and lower the severity of this visual shift.

You can also set the Carousel to fill the height of a parent container via css if the content may be of variable height. Setting the Carousel to full-height via css will pin the pagination controls to the bottom of the container and prevent the controls from changing location as the height of the Carousel Items change.

Do try and ensure content in each Carousel Item is of a similar length and structure.
Do adjust the Carousel to fill the parent container if the Carousel Items are of variable height.

Autoplay

The component supports autoplay with the autoplay property. When the component is initialized with either autoplay or autoplay="paused", the component will automatically rotate through its Carousel Items. The default autoplayDuration is 6000 milliseconds, or 6 seconds. The autoplayDuration can be adjusted to a value that is appropriate for the content being displayed. Avoid overriding the default autoplayDuration with a value that is too short, as this may not provide users with enough time to read or interact with the content.

Do ensure a Carousel Item is displayed long enough for a user to interpret its contents.
Do - if needed - adjust the `autoplayDuration` to a value that is appropriate for the content being displayed.
Avoid using `rotation` when the Carousel contains content that contains dense or complex content.
Avoid overriding the default `autoplayDuration` with a value that is too short.

Pausing autoplay

When a user hovers or focuses the Carousel component, or when a slotted Carousel Item's focusable content is focused, autoplay is paused. If a user directly interacts with the "Play / Pause" button, the Carousel will begin to play regardless of a user's hover or focus.

Toggling autoplay

When present, the autoplay functionality can be set with the play() and stop() methods. If autoplay is not enabled (the component is initialized without autoplay set to true or "paused"), these methods will have no effect.

Accessibility

Keyboard navigation

KeyFunction
TabWhen a calcite-carousel initially receives focus, the component container is focused. If autoplay is enabled and active at this time, the calciteCarouselPause event will emit. If the component container is focused and the currently selected calcite-carousel-item has focusable content, the focus will move to the first focusable item within the calcite-carousel-item. If focus is on the last focusable item within the calcite-carousel-item, focus will return to the Carousel pagination area. If the currently selected calcite-carousel-item does not have focusable content, subsequent Tab interactions will move focus - depending on property configuration - to either the autoplay control, the "previous" calcite-carousel-item button, or the first pagination item. If focus - depending on property configuration - is on the "next" calcite-carousel-item button, or the last pagination item, focus will exit the component.
Tab and ShiftIf focus - depending on property configuration - is on the "previous carousel item" button, or the first pagination item, and the currently selected calcite-carousel-item has focusable content, will return to the last focusable item within the calcite-carousel-item. If focus is on the first focusable item within the calcite-carousel-item, focus will return to the component container. If the component container is focused, focus will exit the component. If autoplay is enabled and active at this time, and the user is not hovering over the component in addition to it being focused, the calciteCarouselResume event will emit and play will resume.
Arrow leftWhen a calcite-carousel is focused, and focus is on the component container, will select and display the previous calcite-carousel-item. If the first calcite-carousel-item is selected and displayed, the last Carousel Item will be selected and displayed. If focus is on the pagination elements (or - depending on property configuration - the "next" calcite-carousel-item / "previous carousel item" buttons), the previous pagination item or "previous carousel item" button will be focused. If focus is on the first pagination item or "previous" calcite-carousel-item button, focus will move to the last pagination item or calcite-carousel-item.
Arrow rightWhen a calcite-carousel is focused, and focus is on the component container, will select and display the next calcite-carousel-item. If the last calcite-carousel-item is selected and displayed, the first calcite-carousel-item will be selected and displayed. If focus is on the pagination elements (or - depending on property configuration - the "next" calcite-carousel-item / "previous" calcite-carousel-item buttons), the last next item or "next" calcite-carousel-item button will be focused. If focus is on the last pagination item or "next" calcite-carousel-item button, focus will move to the first pagination item or "previous" calcite-carousel-item button.
SpaceWhen a calcite-carousel is focused, autoplay is present, and focus is on the component container, starts or pauses the component.
EnterWhen a calcite-carousel is focused, autoplay is present, and focus is on the component container, starts or pauses the component.
HomeWhen a calcite-carousel is focused, and focus is on the component container, will select and display the first calcite-carousel-item. If focus is on the pagination elements (or the next / next buttons if control display mode is "inline" (default)), the first pagination item or "previous" calcite-carousel-item button will be focused.
EndWhen a calcite-carousel is focused, and focus is on the component container, will select and display the last calcite-carousel-item. If focus is on the pagination elements (or the next / next buttons if control display mode is "inline" (default)), the last pagination item or "previous" calcite-carousel-item button will be focused.

API reference

Properties

Slots

Events

Methods

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.