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 shorcuts.
  • 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
Default""
Since1.24

accessibleNameRef​

DescriptionDefines the IDs of the elements that label the input.
Typestring
Default""
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

itemsPerPageS​

DescriptionDefines the number of items per page on small size (up to 640px). One item per page shown by default.
Typenumber
Default1

itemsPerPageM​

DescriptionDefines the number of items per page on medium size (from 640px to 1024px). One item per page shown by default.
Typenumber
Default1

itemsPerPageL​

DescriptionDefines the number of items per page on large size (more than 1024px). One item per page shown by default.
Typenumber
Default1

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

pageIndicatorStyle​

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-l, items-per-page-m and items-per-page-s properties.
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 pageIndicatorStyle is set to "Content", the arrows are placed on the sides of the current page. When pageIndicatorStyle is set to "Navigation", the arrows are placed on the sides of the page indicator.

Page Indicator​

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

Multiple Items per Page​

The items-per-page-s, items-per-page-m and items-per-page-l properties define the number of items per page for given breakpoint ("S", "M" and "L").

Accessible name​

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