Skip to main content

Carousel

The Carousel allows the user to browse through a set of items. The component is mostly used for showing a gallery of images, but can hold any other HTML element.

There are several ways to perform navigation:

  • on desktop - the user can navigate using the navigation arrows or with keyboard shortcuts.
  • on mobile - the user can use swipe gestures.

Usage​

When to use:​

  • The items you want to display are very different from each other.
  • You want to display the items one after the other.

When not to use:​

  • The items you want to display need to be visible at the same time.
  • The items you want to display are uniform and very similar.

Keyboard Handling​

Basic Navigation​

When the ui5-carousel is focused the user can navigate between the items with the following keyboard shortcuts:

  • [Up] or [Down] - Navigates to previous and next item
  • [Left] or [Right] - Navigates to previous and next item

Fast Navigation​

This component provides a build in fast navigation group which can be used via [F6] / [Shift] + [F6] / [Ctrl] + [Alt/Option] / [Down] or [Ctrl] + [Alt/Option] + [Up]. In order to use this functionality, you need to import the following module:

import "@ui5/webcomponents-base/dist/features/F6Navigation.js"

ES6 Module Import​

import "@ui5/webcomponents/dist/Carousel.js";

Properties​

accessibleName​

DescriptionDefines the accessible name of the component.
Typestring | undefined
Defaultundefined
Since1.24

accessibleNameRef​

DescriptionDefines the IDs of the elements that label the input.
Typestring | undefined
Defaultundefined
Since1.24

cyclic​

DescriptionDefines whether the carousel should loop, i.e show the first page after the last page is reached and vice versa.
Typeboolean
Defaultfalse

itemsPerPage​

DescriptionDefines the number of items per page depending on the carousel width.
- 'S' for screens smaller than 600 pixels.
- 'M' for screens greater than or equal to 600 pixels and smaller than 1024 pixels.
- 'L' for screens greater than or equal to 1024 pixels and smaller than 1440 pixels.
- 'XL' for screens greater than or equal to 1440 pixels.
One item per page is shown by default.
Typestring
Default"S1 M1 L1 XL1"

hideNavigationArrows​

DescriptionDefines the visibility of the navigation arrows. If set to true the navigation arrows will be hidden.
Note: The navigation arrows are never displayed on touch devices. In this case, the user can swipe to navigate through the items.
Typeboolean
Defaultfalse
Since1.0.0-rc.15

hidePageIndicator​

DescriptionDefines the visibility of the page indicator. If set to true the page indicator will be hidden.
Typeboolean
Defaultfalse
Since1.0.0-rc.15

pageIndicatorType​

DescriptionDefines the style of the page indicator. Available options are:
- Default - The page indicator will be visualized as dots if there are fewer than 9 pages. If there are more pages, the page indicator will switch to displaying the current page and the total number of pages. (e.g. X of Y)
- Numeric - The page indicator will display the current page and the total number of pages. (e.g. X of Y)
Type"Default" | "Numeric"
Default"Default"
Since1.10

backgroundDesign​

DescriptionDefines the carousel's background design.
Type"Solid" | "Transparent" | "Translucent"
Default"Translucent"
Since1.14

pageIndicatorBackgroundDesign​

DescriptionDefines the page indicator background design.
Type"Solid" | "Transparent" | "Translucent"
Default"Solid"
Since1.14

pageIndicatorBorderDesign​

DescriptionDefines the page indicator border design.
Type"Solid" | "None"
Default"Solid"
Since1.14

arrowsPlacement​

DescriptionDefines the position of arrows.
Available options are:
- Content - the arrows are placed on the sides of the current page.
- Navigation - the arrows are placed on the sides of the page indicator.
Type"Content" | "Navigation"
Default"Content"

visibleItemsIndices​

DescriptionThe indices of the currently visible items of the component.
TypeArray<number>
Default[]
Readonlytrue
Since1.0.0-rc.15

Slots​

default​

DescriptionDefines the content of the component.
TypeArray<HTMLElement>

Events​

DescriptionFired whenever the page changes due to user interaction, when the user clicks on the navigation arrows or while resizing, based on the items-per-page property.
TypeCustomEvent<CarouselNavigateEventDetail>
ParametersselectedIndex: Integer
the current selected index
Since1.0.0-rc.7

Methods​

DescriptionChanges the currently displayed page.
Return typevoid
ParametersitemIndex: number
The index of the target page
Since1.0.0-rc.15

CSS Parts​

NameDescription
contentUsed to style the content of the component

More Samples​

Cyclic​

When the last page is reached, pressing "Forward" will navigate to the start. When the first page is reached, pressing "Backward" will navigate to the last page.

Arrows Placement​

When arrowsPlacement is set to "Content", the arrows are placed on the sides of the current page. When arrowsPlacement is set to "Navigation", the arrows are placed on the sides of the page indicator.

Page Indicator​

When pageIndicatorType is set to "Default", the page indicator appear as dots. When pageIndicatorType is set to "Numeric" - as numbers.

Multiple Items per Page​

The items-per-page property define the number of items per page for given breakpoint ("S", "M", "L" and "XL").

Accessible name​

Use the accessibleName or the accessibleNameRef properties to label the Carousel and improve its accessibility.