Carousel

This component displays a slideshow by cycling through elements (images, text, or custom slides) like a carousel.

Carousel displays a slideshow by cycling through elements (images, text, or custom slides) in a carousel format. It provides an interactive way to present multiple content items in a single interface area with smooth transitions and navigation controls.

Key features:

Multiple orientations: Supports both horizontal and vertical scrolling
Navigation controls: Built-in previous/next buttons with customizable icons
Indicators: Visual dots showing current position and allowing direct navigation
Autoplay functionality: Automatic slide progression with configurable intervals
Loop support: Continuous cycling through slides
Keyboard navigation: Arrow key support for accessibility
Exposed methods: Programmatic control via scrollTo(), scrollNext(), scrollPrev(), canScrollNext(), canScrollPrev()

Behaviors

This component supports the following behaviors:

Behavior	Properties
Animation	`animation`, `animationOptions`
Bookmark	`bookmark`, `bookmarkLevel`, `bookmarkTitle`, `bookmarkOmitFromToc`
Component Label	`label`, `labelPosition`, `labelWidth`, `labelBreak`, `required`, `enabled`, `shrinkToLabel`, `style`, `readOnly`
Publish/Subscribe	`subscribeToTopic`
Tooltip	`tooltip`, `tooltipMarkdown`, `tooltipOptions`
Styling Variant	`variant`

Properties

`autoplay`

default: false

Start scrolling the carousel automatically (true) or not (false).

This property indicates whether the carousel automatically scrolls through slides.

<App>
  <Carousel autoplay autoplayInterval="2000" height="120px" loop>
    <CarouselItem>
      <Card title="Slide 1" />
    </CarouselItem>
    <CarouselItem>
      <Card title="Slide 2" />
    </CarouselItem>
    <CarouselItem>
      <Card title="Slide 3" />
    </CarouselItem>
  </Carousel>
</App>

Example: autoplay

<App>
  <Carousel autoplay autoplayInterval="2000" height="120px" loop>
    <CarouselItem>
      <Card title="Slide 1" />
    </CarouselItem>
    <CarouselItem>
      <Card title="Slide 2" />
    </CarouselItem>
    <CarouselItem>
      <Card title="Slide 3" />
    </CarouselItem>
  </Carousel>
</App>

`autoplayInterval`

default: 5000

Specifies the interval between autoplay transitions.

This property specifies the interval between autoplay transitions in milliseconds.

`controls`

default: true

Display the previous/next controls (true) or not (false).

This property indicates whether the carousel displays navigation controls (previous/next buttons).

<App>
  <Carousel controls="true" height="120px">
    <CarouselItem>Slide 1 with controls</CarouselItem>
    <CarouselItem>Slide 2 with controls</CarouselItem>
  </Carousel>
</App>

Example: controls

<App>
  <Carousel controls="true" height="120px">
    <CarouselItem>Slide 1 with controls</CarouselItem>
    <CarouselItem>Slide 2 with controls</CarouselItem>
  </Carousel>
</App>

`indicators`

default: true

Display the individual slides as buttons (true) or not (false).

This property indicates whether the carousel displays position indicators.

<App>
  <Carousel indicators="true" height="120px">
    <CarouselItem>Slide 1 with indicators</CarouselItem>
    <CarouselItem>Slide 2 with indicators</CarouselItem>
    <CarouselItem>Slide 3 with indicators</CarouselItem>
  </Carousel>
</App>

Example: indicators

<App>
  <Carousel indicators="true" height="120px">
    <CarouselItem>Slide 1 with indicators</CarouselItem>
    <CarouselItem>Slide 2 with indicators</CarouselItem>
    <CarouselItem>Slide 3 with indicators</CarouselItem>
  </Carousel>
</App>

`loop`

default: false

Sets whether the carousel should loop back to the start/end when it reaches the last/first slide.

This property indicates whether the carousel loops continuously from the last slide back to the first.

<App>
  <Carousel loop="true" height="120px">
    <CarouselItem>
      <Card title="First Slide" />
    </CarouselItem>
    <CarouselItem>
      <Card title="Second Slide" />
    </CarouselItem>
    <CarouselItem>
      <Card title="Third Slide" />
    </CarouselItem>
  </Carousel>
</App>

Example: loop

<App>
  <Carousel loop="true" height="120px">
    <CarouselItem>
      <Card title="First Slide" />
    </CarouselItem>
    <CarouselItem>
      <Card title="Second Slide" />
    </CarouselItem>
    <CarouselItem>
      <Card title="Third Slide" />
    </CarouselItem>
  </Carousel>
</App>

`nextIcon`

The icon to display for the next control.

This property specifies the icon to display for the next control button.

<App>
  <Carousel nextIcon="chevronright" prevIcon="chevronleft" height="120px">
    <CarouselItem>Slide 1</CarouselItem>
    <CarouselItem>Slide 2</CarouselItem>
    <CarouselItem>Slide 3</CarouselItem>
  </Carousel>
</App>

Example: custom icons

<App>
  <Carousel nextIcon="chevronright" prevIcon="chevronleft" height="120px">
    <CarouselItem>Slide 1</CarouselItem>
    <CarouselItem>Slide 2</CarouselItem>
    <CarouselItem>Slide 3</CarouselItem>
  </Carousel>
</App>

`orientation`

default: "horizontal"

This property indicates the orientation of the carousel. The horizontal value indicates that the carousel moves horizontally, and the vertical value indicates that the carousel moves vertically.

Available values:

Value	Description
`horizontal`	The component will fill the available space horizontally (default)
`vertical`	The component will fill the available space vertically

This property indicates the orientation of the carousel. The horizontal value indicates that the carousel moves horizontally, and the vertical value indicates that the carousel moves vertically.

Available values:

Value	Description
`horizontal`	The carousel moves horizontally (default)
`vertical`	The carousel moves vertically

<App>
  <Carousel orientation="horizontal" height="120px">
    <CarouselItem>Horizontal Slide 1</CarouselItem>
    <CarouselItem>Horizontal Slide 2</CarouselItem>
  </Carousel>
</App>

Example: orientation

<App>
  <Carousel orientation="horizontal" height="120px">
    <CarouselItem>Horizontal Slide 1</CarouselItem>
    <CarouselItem>Horizontal Slide 2</CarouselItem>
  </Carousel>
</App>

`prevIcon`

The icon to display for the previous control.

This property specifies the icon to display for the previous control button.

`startIndex`

default: 0

The index of the first slide to display.

This property indicates the index of the first slide to display when the carousel initializes.

<App>
  <Carousel startIndex="2" height="120px">
    <CarouselItem>Slide 1</CarouselItem>
    <CarouselItem>Slide 2</CarouselItem>
    <CarouselItem>Slide 3 (starts here)</CarouselItem>
    <CarouselItem>Slide 4</CarouselItem>
  </Carousel>
</App>

Example: startIndex

<App>
  <Carousel startIndex="2" height="120px">
    <CarouselItem>Slide 1</CarouselItem>
    <CarouselItem>Slide 2</CarouselItem>
    <CarouselItem>Slide 3 (starts here)</CarouselItem>
    <CarouselItem>Slide 4</CarouselItem>
  </Carousel>
</App>

`stopAutoplayOnInteraction`

default: true

This property indicates whether autoplay stops on user interaction.

This property indicates whether autoplay stops when the user interacts with the carousel (clicking controls, indicators, or using keyboard navigation).

`transitionDuration`

default: 25

The duration of the transition between slides.

This property indicates the duration of the transition between slides in milliseconds.

Events

`displayDidChange`

This event fires when the active slide of the Carousel changes.

Signature: displayDidChange(activeSlide: number): void

activeSlide: The index of the currently active slide.

This event is triggered when the active slide changes.

The event handler receives the active slide index as a parameter.

<App var.currentSlide="0">
  <Carousel onDisplayDidChange="(index) => currentSlide = index" height="120px">
    <CarouselItem>Slide 1</CarouselItem>
    <CarouselItem>Slide 2</CarouselItem>
    <CarouselItem>Slide 3</CarouselItem>
  </Carousel>
  <Text>Current slide: {currentSlide + 1}</Text>
</App>

Example: displayDidChange

<App var.currentSlide="0">
  <Carousel onDisplayDidChange="(index) => currentSlide = index" height="120px">
    <CarouselItem>Slide 1</CarouselItem>
    <CarouselItem>Slide 2</CarouselItem>
    <CarouselItem>Slide 3</CarouselItem>
  </Carousel>
  <Text>Current slide: {currentSlide + 1}</Text>
</App>

Exposed Methods

`canScrollNext`

This method returns true if the carousel can scroll to the next slide.

Signature: canScrollNext(): boolean

`canScrollPrev`

This method returns true if the carousel can scroll to the previous slide.

Signature: canScrollPrev(): boolean

`scrollNext`

This method scrolls the carousel to the next slide.

Signature: scrollNext(): void

`scrollPrev`

This method scrolls the carousel to the previous slide.

Signature: scrollPrev(): void

`scrollTo`

This method scrolls the carousel to the specified slide index.

Signature: scrollTo(index: number): void

index: The index of the slide to scroll to.

Styling

Theme Variables

Variable	Default Value (Light)	Default Value (Dark)
backgroundColor-control-Carousel	$color-primary	$color-primary
backgroundColor-control-active-Carousel	$color-primary	$color-primary
backgroundColor-control-disabled-Carousel	$color-surface-200	$color-surface-200
backgroundColor-control-hover-Carousel	$color-primary	$color-primary
backgroundColor-indicator-Carousel	$color-surface-200	$color-surface-200
backgroundColor-indicator-active-Carousel	$color-primary	$color-primary
backgroundColor-indicator-hover-Carousel	$color-surface-200	$color-surface-200
borderRadius-control-Carousel	50%	50%
height-Carousel	100%	100%
height-control-Carousel	36px	36px
height-indicator-Carousel	6px	6px
textColor-control-Carousel	$textColor	$textColor
textColor-control-active-Carousel	$color-primary	$color-primary
textColor-control-disabled-Carousel	$textColor-disabled	$textColor-disabled
textColor-control-hover-Carousel	$textColor	$textColor
textColor-indicator-Carousel	$color-primary	$color-primary
textColor-indicator-active-Carousel	$color-primary	$color-primary
textColor-indicator-hover-Carousel	$color-primary	$color-primary
width-Carousel	100%	100%
width-control-Carousel	36px	36px
width-indicator-Carousel	25px	25px

The carousel provides built-in navigation controls that can be customized through theme variables:

Example: Custom control styling

Theme Variables

Variable	Default Value (Light)	Default Value (Dark)
backgroundColor-control-active-Carousel	$color-primary	$color-primary
backgroundColor-control-Carousel	$color-primary	$color-primary
backgroundColor-control-disabled-Carousel	$color-surface-200	$color-surface-200
backgroundColor-control-hover-Carousel	$color-primary	$color-primary
backgroundColor-indicator-active-Carousel	$color-primary	$color-primary
backgroundColor-indicator-Carousel	$color-surface-200	$color-surface-200
backgroundColor-indicator-hover-Carousel	$color-surface-200	$color-surface-200
borderRadius-control-Carousel	50%	50%
height-Carousel	100%	100%
height-control-Carousel	36px	36px
height-indicator-Carousel	6px	6px
textColor-control-active-Carousel	$color-primary	$color-primary
textColor-control-Carousel	$textColor	$textColor
textColor-control-disabled-Carousel	$textColor-disabled	$textColor-disabled
textColor-control-hover-Carousel	$textColor	$textColor
textColor-indicator-active-Carousel	$color-primary	$color-primary
textColor-indicator-Carousel	$color-primary	$color-primary
textColor-indicator-hover-Carousel	$color-primary	$color-primary
width-Carousel	100%	100%
width-control-Carousel	36px	36px
width-indicator-Carousel	25px	25px

Carousel

Behaviors

Properties

autoplay

autoplayInterval

controls

indicators

loop

nextIcon

orientation

prevIcon

startIndex

stopAutoplayOnInteraction

transitionDuration

Events

displayDidChange

Exposed Methods

canScrollNext

canScrollPrev

scrollNext

scrollPrev

scrollTo

Styling

Theme Variables

Navigation Controls

Theme Variables

`autoplay`

`autoplayInterval`

`controls`

`indicators`

`loop`

`nextIcon`

`orientation`

`prevIcon`

`startIndex`

`stopAutoplayOnInteraction`

`transitionDuration`

`displayDidChange`

`canScrollNext`

`canScrollPrev`

`scrollNext`

`scrollPrev`

`scrollTo`