---
title: "Carousel"
description: "Browse cards by swiping, using the arrow keys or pressing the navigation buttons."
---

# Carousel

Browse cards by swiping, using the arrow keys or pressing the navigation buttons.

## Installation

Install the shared package once in your Exact app. This version is a beta.

```sh
bun add --exact @rightui/ui@0.4.0-beta.4
```

Or choose another package manager:

```sh
npm install --save-exact @rightui/ui@0.4.0-beta.4
pnpm add --save-exact @rightui/ui@0.4.0-beta.4
yarn add --exact @rightui/ui@0.4.0-beta.4
```

Exact compilation uses Bun 1.4.2. Register Geist and Newsreader, declare the font marker and add the root provider using [Installation](/docs/installation).

### Manual source setup

Install an editable copy of the complete package:

```sh
mkdir -p vendor/rightui vendor/rightui-ui
npm pack @rightui/ui@0.4.0-beta.4 --pack-destination vendor/rightui
tar -xzf ./vendor/rightui/rightui-ui-0.4.0-beta.4.tgz -C vendor/rightui-ui --strip-components=1
bun add file:./vendor/rightui-ui
```

Keep package.json, the Contract files, ui.tamber, assets and licenses together.

### Import

```contract
use Carousel, CarouselSlide, CarouselTrack, CarouselControl, CarouselAdvanced, CarouselFrameAdvanced, CarouselItemAdvanced, CarouselImageAdvanced, CarouselSlideData from "@rightui/ui"
```

## Usage

Use Carousel for text slides, or compose CarouselTrack and CarouselSlide around custom content. Set fullWidth to reach the edges of the parent. Set showControls to false to place CarouselControl anywhere, passing the track ID as target and sharing its selection and change action.

## Example

```contract
use CarouselControl, CarouselTrack, CarouselSlide, CardStyle, FontWeights, uiFontFamily from "@rightui/ui"

component NumberedCarousel
  props
    id: string
    label: string
    width: number
    visible: number
    spacing: number
    vertical: bool
    rtl: bool
    autoplay: bool
    fullWidth: bool
    externalControls: bool
    showPosition: bool
    reduced: bool
  inject
    uiFont: string
    uiWeights: FontWeights
    carouselTick: number
  state selected = 0
  state stopped = false
  state hovered = false
  state pausedAt = 0
  state resumedAt = 0
  derive playing = autoplay and not reduced and not stopped
  derive position = playing ? (pausedAt + (hovered ? 0 : carouselTick - resumedAt)) % 5 : selected
  derive axis = vertical ? "vertical" : "horizontal"
  derive viewportWidth = max(48, min(width - (vertical ? 0 : 96), width < 320 ? 192 : visible > 1 ? 384 : 320))
  derive height = vertical ? 270 : viewportWidth / visible
  action select(i: number)
    selected = i
    stopped = true
  action hover(active: bool)
    if playing and hovered != active
      if active
        pausedAt = position
      else
        resumedAt = carouselTick
      hovered = active
  view
    column width="100%" align-items="center"
      column width=(fullWidth ? "100%" : (viewportWidth + (vertical ? 0 : 96)).toString() + "px") max-width="100%" min-width=0 hover=hover
        if externalControls
          row align-items="center" gap="ui.space-8" padding-bottom="ui.space-12"
            text label flex=1 role="heading" aria-level=3 font-weight=uiWeights.semibold font-family=uiFontFamily(uiFont) data-rightui-font="body"
            for prev in [true, false] key=prev
              CarouselControl(target=id, previous=prev, value=position, count=5, visible=visible, loop=autoplay, orientation=axis, rtl=rtl, change=select)
        CarouselTrack(id=id, label=label, value=position, count=5, orientation=axis, height=height, visible=visible, rtl=rtl, showPosition=showPosition, fullWidth=fullWidth, showControls=not externalControls, loop=autoplay, reduced=reduced, change=select)
          for n, i in [1, 2, 3, 4, 5] key=n
            CarouselSlide(id=id + "-slide-" + n.toString(), label="Card " + n.toString(), index=i, value=position, count=5, orientation=axis, height=height, reduced=reduced, rtl=rtl, visible=visible)
              column padding=spacing height="100%" width="100%" box-sizing="border-box"
                column class=CardStyle padding=0 flex=1 min-height=0 align-items="center" justify-content="center"
                  text n.toString() font-size=(visible == 1 ? "ui.text-display" : "ui.text-2xl") font-weight=uiWeights.semibold font-family=uiFontFamily(uiFont) data-rightui-font="body"

component Demo
  props
    width: number
    reduced: bool
  inject
    uiFont: string
    uiWeights: FontWeights
  derive perPage = width >= 500 ? 3 : 2
  view
    column gap="ui.space-32" width="100%" min-width=0
      NumberedCarousel(id="carousel-basic", label="Featured cards", width=width, fullWidth=false, externalControls=false, visible=1, spacing=4, vertical=false, rtl=false, autoplay=false, showPosition=false, reduced=reduced)
      NumberedCarousel(id="carousel-full-width", label="Full width", width=width, fullWidth=true, externalControls=true, visible=1, spacing=0, vertical=false, rtl=false, autoplay=false, showPosition=false, reduced=reduced)
      text "Sizes" role="heading" aria-level=3 font-weight=uiWeights.semibold font-family=uiFontFamily(uiFont) data-rightui-font="body"
      NumberedCarousel(id="carousel-sizes", label="Sizes", width=width, fullWidth=false, externalControls=false, visible=perPage, spacing=8, vertical=false, rtl=false, autoplay=false, showPosition=false, reduced=reduced)
      text "Spacing" role="heading" aria-level=3 font-weight=uiWeights.semibold font-family=uiFontFamily(uiFont) data-rightui-font="body"
      NumberedCarousel(id="carousel-spacing", label="Spacing", width=width, fullWidth=false, externalControls=false, visible=perPage, spacing=3, vertical=false, rtl=false, autoplay=false, showPosition=false, reduced=reduced)
      text "Vertical" role="heading" aria-level=3 font-weight=uiWeights.semibold font-family=uiFontFamily(uiFont) data-rightui-font="body"
      NumberedCarousel(id="carousel-vertical", label="Vertical", width=width, fullWidth=false, externalControls=false, visible=2, spacing=4, vertical=true, rtl=false, autoplay=false, showPosition=false, reduced=reduced)
      text "Current slide" role="heading" aria-level=3 font-weight=uiWeights.semibold font-family=uiFontFamily(uiFont) data-rightui-font="body"
      NumberedCarousel(id="carousel-api", label="Current slide", width=width, fullWidth=false, externalControls=false, visible=1, spacing=4, vertical=false, rtl=false, autoplay=false, showPosition=true, reduced=reduced)
      text "Autoplay" role="heading" aria-level=3 font-weight=uiWeights.semibold font-family=uiFontFamily(uiFont) data-rightui-font="body"
      NumberedCarousel(id="carousel-autoplay", label="Autoplay", width=width, fullWidth=false, externalControls=false, visible=1, spacing=4, vertical=false, rtl=false, autoplay=true, showPosition=false, reduced=reduced)
      text "Right to left" role="heading" aria-level=3 font-weight=uiWeights.semibold font-family=uiFontFamily(uiFont) data-rightui-font="body"
      NumberedCarousel(id="carousel-rtl", label="Right to left", width=width, fullWidth=false, externalControls=false, visible=1, spacing=4, vertical=false, rtl=true, autoplay=false, showPosition=false, reduced=reduced)

```

## API Reference

| Property | Type |
| --- | --- |
| Carousel.id | string |
| Carousel.slides | string[] |
| Carousel.loop | bool |
| Carousel.reduced | bool |
| CarouselItemAdvanced.id | string |
| CarouselItemAdvanced.label | string |
| CarouselItemAdvanced.index | number |
| CarouselItemAdvanced.value | number |
| CarouselItemAdvanced.count | number |
| CarouselItemAdvanced.orientation | string |
| CarouselItemAdvanced.height | number |
| CarouselItemAdvanced.reduced | bool |
| CarouselSlide.id | string |
| CarouselSlide.label | string |
| CarouselSlide.index | number |
| CarouselSlide.value | number |
| CarouselSlide.count | number |
| CarouselSlide.orientation | string |
| CarouselSlide.height | number |
| CarouselSlide.reduced | bool |
| CarouselSlide.visible | number |
| CarouselSlide.rtl | bool |
| CarouselFrameAdvanced.id | string |
| CarouselFrameAdvanced.label | string |
| CarouselFrameAdvanced.value | number |
| CarouselFrameAdvanced.count | number |
| CarouselFrameAdvanced.orientation | string |
| CarouselFrameAdvanced.height | number |
| CarouselFrameAdvanced.loop | bool |
| CarouselFrameAdvanced.reduced | bool |
| CarouselFrameAdvanced.change | action |
| CarouselTrack.id | string |
| CarouselTrack.label | string |
| CarouselTrack.value | number |
| CarouselTrack.count | number |
| CarouselTrack.orientation | string |
| CarouselTrack.height | number |
| CarouselTrack.loop | bool |
| CarouselTrack.reduced | bool |
| CarouselTrack.change | action |
| CarouselTrack.visible | number |
| CarouselTrack.rtl | bool |
| CarouselTrack.showPosition | bool |
| CarouselTrack.fullWidth | bool |
| CarouselTrack.showControls | bool |
| CarouselControl.target | string |
| CarouselControl.previous | bool |
| CarouselControl.value | number |
| CarouselControl.count | number |
| CarouselControl.visible | number |
| CarouselControl.loop | bool |
| CarouselControl.orientation | string |
| CarouselControl.rtl | bool |
| CarouselControl.change | action |
| CarouselImageAdvanced.id | string |
| CarouselImageAdvanced.src | string |
| CarouselImageAdvanced.alt | string |
| CarouselImageAdvanced.ratio | number |
| CarouselAdvanced.id | string |
| CarouselAdvanced.label | string |
| CarouselAdvanced.slides | CarouselSlideData[] |
| CarouselAdvanced.value | number |
| CarouselAdvanced.orientation | string |
| CarouselAdvanced.height | number |
| CarouselAdvanced.imageRatio | number |
| CarouselAdvanced.loop | bool |
| CarouselAdvanced.reduced | bool |
| CarouselAdvanced.change | action |

## Autoplay

The autoplay example reads carouselTick from the root. Enable its timer while the carousel is on screen and motion is allowed. Manual navigation stops autoplay.

```contract
  state carouselTick = 0
  provide
    carouselTick = carouselTick
  action advanceCarousel
    carouselTick = carouselTick + 1
  task carouselClock when top(nav).name == "component_carousel" and not viewport.prefersReducedMotion
    every(2000, advanceCarousel)
```

## Source

File: packages/ui/carousel.contract

```contract
use CarouselTrack, CarouselSlide from "./layout-advanced.contract"
use FontWeights from "./typography-context.contract"
use uiFontFamily from "./typography-context.contract"
use Control, CardStyle from "./styles.contract"
component Carousel
  props
    id: string
    slides: string[]
    loop: bool
    reduced: bool
  inject
    uiWeights: FontWeights
    uiFont: string
  state index = 0
  derive total = slides.length
  derive currentIndex = max(0, min(total - 1, index))
  action choose(i: number)
    index = i
  view
    column min-width=0 gap="ui.space-8"
      CarouselTrack(id=id, label="Featured slides", value=currentIndex, count=total, orientation="horizontal", height=220, loop=loop, reduced=reduced, change=choose, visible=1, rtl=false, showPosition=true, fullWidth=false, showControls=true)
        for slide, i in slides key=i
          CarouselSlide(id=id + "-slide-" + i.toString(), label=slide, index=i, value=currentIndex, count=total, orientation="horizontal", height=220, reduced=reduced, visible=1, rtl=false)
            column class=CardStyle height="100%" align-items="center" justify-content="center"
              text (i + 1).toString() font-size="ui.text-display" font-weight=uiWeights.semibold font-family=uiFontFamily(uiFont) data-rightui-font="body"
              text slide font-size="ui.text-base" font-family=uiFontFamily(uiFont) data-rightui-font="body"
      row gap="ui.space-8" align-items="center" flex-wrap="wrap" justify-content="center"
        for slide, i in slides key=i
          button class=Control font-weight=uiWeights.medium id=(id + "-dot-" + i.toString()) testId=(id + "-dot-" + i.toString()) press=choose(i) aria-label=("Go to slide " + (i + 1).toString()) aria-pressed=(currentIndex == i)
            padding="0px" width="ui.space-24" height="ui.space-24" min-height="ui.space-24" border="0" background-color="transparent" display="flex" align-items="center" justify-content="center"
            view width="ui.space-8" height="ui.space-8" border-radius="ui.radius-full" background-color=(currentIndex == i ? "ui.primary" : "ui.border")

```
