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
<calcite-carousel label="Great new features">
<calcite-carousel-item label="Pie chart">
<div class="custom-content">
<calcite-chip scale="l" icon="pie-chart"></calcite-chip>
<span>
Pie charts are a great way to visualize data. They're easy to understand
and can be used in a variety of ways.
</span>
</div>
</calcite-carousel-item>
<calcite-carousel-item label="Scatter plot">
<div class="custom-content">
<calcite-chip scale="l" icon="graph-scatter-plot"></calcite-chip>
<span>
The scatter plot displays the relationship between multiple variables. It's a
great way to visualize data.
</span>
</div>
</calcite-carousel-item>
<calcite-carousel-item label="Histogram">
<div class="custom-content">
<calcite-chip scale="l" icon="box-chart"></calcite-chip>
<span>
Box charts are another great way to visualize data to illustrate trends and ranges.
</span>
<calcite-button icon-start="graph-moving-average" kind="neutral">Browse examples</calcite-button>
</div>
</calcite-carousel-item>
<calcite-carousel-item label="Heat chart">
<div class="custom-content">
<calcite-chip scale="l" icon="heat-chart"></calcite-chip>
<span>
The heat chart bins data into a grid and uses color or saturation to
represent the values.
</span>
</div>
</calcite-carousel-item>
</calcite-carousel>
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.
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.
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 autoplay
is 6000 milliseconds, or 6 seconds. The autoplay
can be adjusted to a value that is appropriate for the content being displayed. Avoid overriding the default autoplay
with a value that is too short, as this may not provide users with enough time to read or interact with the content.
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
Key | Function |
---|---|
Tab | When a calcite-carousel initially receives focus, the component container is focused. If autoplay is enabled and active at this time, the calcite 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 Shift | If 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 calcite event will emit and play will resume. |
Arrow left | When 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 right | When 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. |
Space | When a calcite-carousel is focused, autoplay is present, and focus is on the component container, starts or pauses the component. |
Enter | When a calcite-carousel is focused, autoplay is present, and focus is on the component container, starts or pauses the component. |
Home | When 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. |
End | When 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
Property | Attribute | Description | Type | Default |
---|---|---|---|---|
arrowType | arrow-type | Specifies how and if the "previous" and "next" arrows are displayed. | "edge" | "inline" | "none" | "inline" |
autoplay | autoplay | When true , the carousel will autoplay and controls will be displayed. When "paused" at time of initialization, the carousel will not autoplay, but controls will be displayed. | "" | "paused" | boolean | false |
autoplayDuration | autoplay-duration | When autoplay is true , specifies in milliseconds the length of time to display each Carousel Item. | number | 6000 |
controlOverlay | control-overlay | Specifies if the component's controls are positioned absolutely on top of slotted Carousel Items. | boolean | false |
disabled | disabled | When true , interaction is prevented and the component is displayed with lower opacity. | boolean | false |
label | label | Accessible name for the component. | string | |
messageOverrides | Use this property to override individual strings used by the component. | {
previous?: string;
next?: string;
play?: string;
pause?: string;
carousel?: string;
carouselItemProgress?: string;
} | ||
selectedItem | The component's selected calcite-carousel-item . | HTMLCalciteCarouselItemElement |
Slots
Name | Description |
---|---|
default (unnamed) | A slot for adding calcite-carousel-item s. |
Events
Name | Description | Behavior |
---|---|---|
calciteCarouselChange | Fires when the selected calcite-carousel-item changes. | |
calciteCarouselPause | Fires when the carousel autoplay state pauses due to a user hovering over the component or focusing on the component or slotted content | |
calciteCarouselPlay | Fires when the carousel autoplay is invoked by the user. | |
calciteCarouselResume | Fires when the carousel autoplay state resumes due to a user no longer hovering over the component or focusing on the component or slotted content | |
calciteCarouselStop | Fires when the carousel autoplay state is stopped by a user. |
Methods
Name | Description | Signature |
---|---|---|
componentOnReady | Create a promise that resolves once component is fully loaded. | componentOnReady(): Promise<void> |
play | Play the carousel. If autoplay is not enabled (initialized either to true or "paused" ), these methods will have no effect. | play(): Promise<void> |
setFocus | Sets focus on the component. | setFocus(): Promise<void> |
stop | Stop the carousel. If autoplay is not enabled (initialized either to true or "paused" ), these methods will have no effect. | stop(): Promise<void> |