DisplayReact

Carousel

Slides in a row that scrolls, with buttons to the previous and next page, a tab per page and an optional rotation.

Rendered by React 19.3.1

Loading React…

import { Carousel } from '@hamur/react/carousel'

const slides = [
  { title: 'Dunes', text: 'Wind sets the shape of the sand.' },
  { title: 'Glacier', text: 'Ice that moves a few metres a year.' },
  { title: 'Harbor', text: 'Boats in at dusk, out before dawn.' },
  { title: 'Canyon', text: 'A river cut it over millions of years.' },
  { title: 'Forest', text: 'Rain on moss and old cedar.' },
]

export default function CarouselExample() {
  return (
    <Carousel.Root className="carousel" aria-label="Places">
      <div className="carousel-bar">
        <Carousel.Value className="carousel-value" />
        <Carousel.Previous
          className="button button-square carousel-arrow carousel-prev"
        />
        <Carousel.Next
          className="button button-square carousel-arrow carousel-next"
        />
      </div>
      <Carousel.Viewport className="carousel-viewport" tabIndex={0}>
        {slides.map((slide) => (
          <Carousel.Slide key={slide.title} className="carousel-slide">
            <p className="carousel-slide-title">{slide.title}</p>
            <p className="muted">{slide.text}</p>
          </Carousel.Slide>
        ))}
      </Carousel.Viewport>
      <Carousel.TabList className="carousel-tabs">
        {(page) => <Carousel.Tab page={page.index} className="carousel-tab" />}
      </Carousel.TabList>
    </Carousel.Root>
  )
}

Not measured yetTests passing in React

Not measured yetSize

Not measured yetMemory

Not measured yetSpeed

[N] commits

Installation

npm i @hamur/react

Not on npm yet. The package goes out under the chosen name.

Anatomy

Import the component and assemble its parts:

<Carousel.Root>
  <Carousel.Value />
  <Carousel.Previous />
  <Carousel.Next />
  <Carousel.Viewport>
    <Carousel.Slide />
  </Carousel.Viewport>
  <Carousel.TabList>
    <Carousel.Tab />
  </Carousel.TabList>
</Carousel.Root>

// Not in this example: Carousel.AutoplayControl

Examples

Multiple

Eight slides three to a view with the fourth peeking: Previous and Next move by three, and there are three tabs, the last one "Slides 7 to 8".

CarouselMultiple.tsx

import { Carousel } from '@hamur/react/carousel'

const items = [
  'Linen shirt',
  'Wool scarf',
  'Canvas tote',
  'Leather belt',
  'Cotton socks',
  'Rain jacket',
  'Knit beanie',
  'Denim cap',
]

export default function CarouselMultipleExample() {
  return (
    <Carousel.Root className="carousel carousel-multiple" aria-label="New arrivals">
      <div className="carousel-bar">
        <Carousel.Value className="carousel-value" />
        <Carousel.Previous className="button button-square carousel-arrow carousel-prev" />
        <Carousel.Next className="button button-square carousel-arrow carousel-next" />
      </div>
      <Carousel.Viewport className="carousel-viewport" tabIndex={0}>
        {items.map((item) => (
          <Carousel.Slide key={item} className="carousel-slide">
            <p className="carousel-slide-title">{item}</p>
          </Carousel.Slide>
        ))}
      </Carousel.Viewport>
      <Carousel.TabList className="carousel-tabs">
        {(page) => <Carousel.Tab page={page.index} className="carousel-tab" />}
      </Carousel.TabList>
    </Carousel.Root>
  )
}

Autoplay

autoplay with loop, the AutoplayControl first in the bar, and a note that the rotation starts stopped under reduced motion.

CarouselAutoplay.tsx

import { Carousel } from '@hamur/react/carousel'

const slides = [
  { title: 'Dunes', text: 'Wind sets the shape of the sand.' },
  { title: 'Glacier', text: 'Ice that moves a few metres a year.' },
  { title: 'Harbor', text: 'Boats in at dusk, out before dawn.' },
  { title: 'Canyon', text: 'A river cut it over millions of years.' },
  { title: 'Forest', text: 'Rain on moss and old cedar.' },
]

export default function CarouselAutoplayExample() {
  return (
    <div className="stack">
      <Carousel.Root className="carousel" aria-label="Places" autoplay loop>
        <div className="carousel-bar">
          <Carousel.AutoplayControl className="button button-square carousel-play" />
          <Carousel.Value className="carousel-value" />
          <Carousel.Previous className="button button-square carousel-arrow carousel-prev" />
          <Carousel.Next className="button button-square carousel-arrow carousel-next" />
        </div>
        <Carousel.Viewport className="carousel-viewport" tabIndex={0}>
          {slides.map((slide) => (
            <Carousel.Slide key={slide.title} className="carousel-slide">
              <p className="carousel-slide-title">{slide.title}</p>
              <p className="muted">{slide.text}</p>
            </Carousel.Slide>
          ))}
        </Carousel.Viewport>
        <Carousel.TabList className="carousel-tabs">
          {(page) => <Carousel.Tab page={page.index} className="carousel-tab" />}
        </Carousel.TabList>
      </Carousel.Root>
      <p className="muted">
        A new slide every five seconds. It waits while the pointer is over it, stops when the
        keyboard moves into it, and starts stopped when your system asks for reduced motion.
      </p>
    </div>
  )
}

Thumbnails

A Tab per slide with a picture and the slide's title, which names it.

CarouselThumbnails.tsx

import { Carousel } from '@hamur/react/carousel'

const slides = [
  { title: 'Dunes', text: 'Wind sets the shape of the sand.' },
  { title: 'Glacier', text: 'Ice that moves a few metres a year.' },
  { title: 'Harbor', text: 'Boats in at dusk, out before dawn.' },
  { title: 'Canyon', text: 'A river cut it over millions of years.' },
  { title: 'Forest', text: 'Rain on moss and old cedar.' },
]

export default function CarouselThumbnailsExample() {
  return (
    <Carousel.Root className="carousel" aria-label="Places">
      <div className="carousel-bar">
        <Carousel.Value className="carousel-value" />
        <Carousel.Previous className="button button-square carousel-arrow carousel-prev" />
        <Carousel.Next className="button button-square carousel-arrow carousel-next" />
      </div>
      <Carousel.Viewport className="carousel-viewport" tabIndex={0}>
        {slides.map((slide) => (
          <Carousel.Slide key={slide.title} className="carousel-slide">
            <p className="carousel-slide-title">{slide.title}</p>
            <p className="muted">{slide.text}</p>
          </Carousel.Slide>
        ))}
      </Carousel.Viewport>
      <Carousel.TabList className="carousel-thumbs">
        {slides.map((slide, index) => (
          <Carousel.Tab key={slide.title} page={index} className="carousel-thumb">
            {slide.title}
          </Carousel.Tab>
        ))}
      </Carousel.TabList>
    </Carousel.Root>
  )
}

Vertical

orientation vertical: the slides scroll up and down, and the tabs sit between Previous and Next in a column.

CarouselVertical.tsx

import { Carousel } from '@hamur/react/carousel'

const slides = [
  { title: 'Dunes', text: 'Wind sets the shape of the sand.' },
  { title: 'Glacier', text: 'Ice that moves a few metres a year.' },
  { title: 'Harbor', text: 'Boats in at dusk, out before dawn.' },
  { title: 'Canyon', text: 'A river cut it over millions of years.' },
]

export default function CarouselVerticalExample() {
  return (
    <Carousel.Root
      className="carousel carousel-vertical"
      aria-label="Places"
      orientation="vertical"
    >
      <div className="carousel-side">
        <Carousel.Previous className="button button-square carousel-arrow carousel-prev" />
        <Carousel.TabList className="carousel-tabs">
          {(page) => <Carousel.Tab page={page.index} className="carousel-tab" />}
        </Carousel.TabList>
        <Carousel.Next className="button button-square carousel-arrow carousel-next" />
      </div>
      <Carousel.Viewport className="carousel-viewport" tabIndex={0}>
        {slides.map((slide) => (
          <Carousel.Slide key={slide.title} className="carousel-slide">
            <p className="carousel-slide-title">{slide.title}</p>
            <p className="muted">{slide.text}</p>
          </Carousel.Slide>
        ))}
      </Carousel.Viewport>
    </Carousel.Root>
  )
}

Loop

loop on three slides: Previous on the first goes to the last and Next on the last to the first.

CarouselLoop.tsx

import { Carousel } from '@hamur/react/carousel'

const slides = [
  { title: 'Dunes', text: 'Wind sets the shape of the sand.' },
  { title: 'Glacier', text: 'Ice that moves a few metres a year.' },
  { title: 'Harbor', text: 'Boats in at dusk, out before dawn.' },
]

export default function CarouselLoopExample() {
  return (
    <Carousel.Root className="carousel" aria-label="Places" loop>
      <div className="carousel-bar">
        <Carousel.Value className="carousel-value" />
        <Carousel.Previous className="button button-square carousel-arrow carousel-prev" />
        <Carousel.Next className="button button-square carousel-arrow carousel-next" />
      </div>
      <Carousel.Viewport className="carousel-viewport" tabIndex={0}>
        {slides.map((slide) => (
          <Carousel.Slide key={slide.title} className="carousel-slide">
            <p className="carousel-slide-title">{slide.title}</p>
            <p className="muted">{slide.text}</p>
          </Carousel.Slide>
        ))}
      </Carousel.Viewport>
    </Carousel.Root>
  )
}

Controlled

value in the example's state: onValueChange writes it and its reason, and First and Last outside the carousel set it.

CarouselControlled.tsx

import * as React from 'react'
import { Carousel } from '@hamur/react/carousel'

const slides = [
  { title: 'Dunes', text: 'Wind sets the shape of the sand.' },
  { title: 'Glacier', text: 'Ice that moves a few metres a year.' },
  { title: 'Harbor', text: 'Boats in at dusk, out before dawn.' },
  { title: 'Canyon', text: 'A river cut it over millions of years.' },
  { title: 'Forest', text: 'Rain on moss and old cedar.' },
]

export default function CarouselControlledExample() {
  const [value, setValue] = React.useState(0)
  const [reason, setReason] = React.useState('none yet')
  return (
    <div className="stack">
      <Carousel.Root
        className="carousel"
        aria-label="Places"
        value={value}
        onValueChange={(next, details) => {
          setValue(next)
          setReason(details.reason)
        }}
      >
        <div className="carousel-bar">
          <Carousel.Value className="carousel-value" />
          <Carousel.Previous className="button button-square carousel-arrow carousel-prev" />
          <Carousel.Next className="button button-square carousel-arrow carousel-next" />
        </div>
        <Carousel.Viewport className="carousel-viewport" tabIndex={0}>
          {slides.map((slide) => (
            <Carousel.Slide key={slide.title} className="carousel-slide">
              <p className="carousel-slide-title">{slide.title}</p>
              <p className="muted">{slide.text}</p>
            </Carousel.Slide>
          ))}
        </Carousel.Viewport>
      </Carousel.Root>
      <div className="carousel-bar">
        <button type="button" className="button" onClick={() => setValue(0)}>
          First
        </button>
        <button type="button" className="button" onClick={() => setValue(slides.length - 1)}>
          Last
        </button>
      </div>
      <p className="muted">
        Value {value} · {reason}
      </p>
    </div>
  )
}

Cards

Six linked cards two to a view with offscreenSlides="interactive" and mouseDrag.

CarouselCards.tsx

import { Carousel } from '@hamur/react/carousel'

const articles = [
  { id: 'scroll-snap', title: 'Scroll snap in practice', text: '6 min read' },
  { id: 'focus', title: 'Where focus should go', text: '4 min read' },
  { id: 'motion', title: 'Motion people can stop', text: '5 min read' },
  { id: 'targets', title: 'Targets big enough to hit', text: '3 min read' },
  { id: 'names', title: 'Names a screen reader says', text: '7 min read' },
  { id: 'tabs', title: 'Tabs that pick a slide', text: '4 min read' },
]

export default function CarouselCardsExample() {
  return (
    <Carousel.Root
      className="carousel carousel-cards"
      aria-label="Articles"
      offscreenSlides="interactive"
      mouseDrag
    >
      <div className="carousel-bar">
        <Carousel.Value className="carousel-value" />
        <Carousel.Previous className="button button-square carousel-arrow carousel-prev" />
        <Carousel.Next className="button button-square carousel-arrow carousel-next" />
      </div>
      <Carousel.Viewport className="carousel-viewport">
        {articles.map((article) => (
          <Carousel.Slide key={article.id} className="carousel-slide">
            <a className="carousel-card" href={`#${article.id}`}>
              <span className="carousel-slide-title">{article.title}</span>
              <span className="muted">{article.text}</span>
            </a>
          </Carousel.Slide>
        ))}
      </Carousel.Viewport>
    </Carousel.Root>
  )
}

API reference

34 props across 9 parts, in React syntax. className, style, render are listed once, under Shared props.

AutoplayControl`Carousel.AutoplayControl`

Starts and stops the rotation; named by what pressing it does. Not rendered without autoplay on the Root. Renders a <button>.

AutoplayControl props
Prop	Type	Default
`nativeButton`Whether the component renders a native `<button>` element when replacing it	`boolean`	`true`

AutoplayControl data attributes
Data attribute	Description
`data-playing`	Present while rotation is on.

Next`Carousel.Next`

Goes to the next page. It is aria-disabled, not disabled, on the last page without loop, so it keeps focus. Renders a <button>.

Next props
Prop	Type	Default
`disabled`Whether the control should ignore user interaction.	`boolean`	`false`
`focusableWhenDisabled`Whether the control stays focusable when it is disabled, with `aria-disabled`.	`boolean`	`true`
`nativeButton`Whether the component renders a native `<button>` element when replacing it	`boolean`	`true`

Next data attributes
Data attribute	Description
`data-disabled`	Present when the control is disabled.

Previous`Carousel.Previous`

Goes to the previous page, or to the start of the current one when a scroll rested past it. It is aria-disabled, not disabled, on the first page without loop, so it keeps focus. Renders a <button>.

Previous props
Prop	Type	Default
`disabled`Whether the control should ignore user interaction.	`boolean`	`false`
`focusableWhenDisabled`Whether the control stays focusable when it is disabled, with `aria-disabled`.	`boolean`	`true`
`nativeButton`Whether the component renders a native `<button>` element when replacing it	`boolean`	`true`

Previous data attributes
Data attribute	Description
`data-disabled`	Present when the control is disabled.

Root`Carousel.Root`

Groups all parts of the carousel: a region with the role description "carousel". Renders a <div>.

Root props
Prop	Type	Default
`value`The index of the current slide, 0-based.	`number`	`—`
`defaultValue`The index of the slide shown when the component is initially rendered.	`number`	`0`
`onValueChange`Event handler called when the current slide changes.	`((value: number, eventDetails: CarouselRootChangeEventDetails) => void)`	`—`
`onValueChangeComplete`Event handler called when the scroll that brought the value has settled.	`((value: number) => void)`	`—`
`orientation`The axis the slides scroll on.	`CarouselOrientation`	`'horizontal'`
`align`Where a slide snaps in the Viewport.	`CarouselAlign`	`'start'`
`slidesPerMove`How far Previous and Next move: `'auto'` by a page (the slides in view), or a number of	`CarouselSlidesPerMove`	`'auto'`
`snapType`The CSS scroll snap strictness.	`CarouselSnapType`	`'mandatory'`
`loop`Whether Previous on the first page goes to the last page and Next on the last to the first.	`boolean`	`false`
`autoplay`Whether the slides rotate automatically.	`boolean`	`false`
`autoplayInterval`The time each page is shown while rotating, in milliseconds.	`number`	`5000`
`playing`Whether rotation runs.	`boolean`	`—`
`defaultPlaying`Whether rotation runs when the component is initially rendered, with `autoplay`.	`boolean`	`true`
`onPlayingChange`Event handler called when rotation starts or stops.	`((playing: boolean, eventDetails: CarouselRootPlayingChangeEventDetails) => void)`	`—`
`mouseDrag`Whether a mouse drag scrolls the Viewport.	`boolean`	`false`
`offscreenSlides`Whether a slide with no part in view is `inert`.	`CarouselOffscreenSlides`	`'inert'`
`scrollBehavior`How the component's own scrolls move: always `'instant'` under	`CarouselScrollBehavior`	`'smooth'`
`labels`The texts, in English by default.	`Partial<CarouselLabels>`	`—`
`actionsRef`A ref to imperative actions: `scrollTo(index)`, `next()`, `previous()`, `play()` and `stop()`.	`React.RefObject<CarouselRootActions \| null>`	`—`

Root data attributes
Data attribute	Description
`data-orientation`	The axis the slides scroll on.
`data-scrolling`	Present while the Viewport is scrolling.
`data-dragging`	Present while a mouse drag is in progress.
`data-playing`	Present while rotation is on.
`data-paused`	Present while rotation is on but held by hover, a hidden page or a drag.
`data-at-start`	Present when the Viewport shows the start of its range.
`data-at-end`	Present when the Viewport shows the end of its range.

Slide`Carousel.Slide`

A slide: a group named "N of M", or a tab panel when the carousel has a TabList. Its index is its position among the slides. Renders a <div>.

Slide data attributes
Data attribute	Description
`data-index`	The slide's index among the slides, 0-based.
`data-active`	Present when the slide is the current value.
`data-in-view`	Present when part of the slide is in view.
`data-orientation`	The axis the slides scroll on.

Tab`Carousel.Tab`

Selects a page and scrolls to it; selected while its page is the current one. Renders a <button>.

Tab props
Prop	Type	Default
`page`requiredThe page the tab selects, 0-based.	`number`	`—`
`disabled`Whether the tab should ignore user interaction.	`boolean`	`false`
`nativeButton`Whether the component renders a native `<button>` element when replacing it	`boolean`	`true`

Tab data attributes
Data attribute	Description
`data-index`	The page of the tab, 0-based.
`data-active`	Present when the tab's page is the current one.
`data-disabled`	Present when the tab is disabled.

TabList`Carousel.TabList`

Groups the tabs that pick a page, one per page, as one Tab stop: the arrow keys move focus and, with activateOnFocus, select the page. Renders a <div>.

TabList props
Prop	Type	Default
`activateOnFocus`Whether moving focus with the arrow keys also selects the page.	`boolean`	`true`
`loopFocus`Whether the arrow keys move focus from the last tab to the first and back.	`boolean`	`true`
`children`The tabs, or a function that renders the tab of each page.	`React.ReactNode \| ((page: CarouselTabListPage, index: number) => React.ReactNode)`	`—`

TabList data attributes
Data attribute	Description
`data-orientation`	The axis the slides scroll on.

Value`Carousel.Value`

The current page as text, "2 of 5". Plain text, not a live region: the Viewport is. Renders a <span>.

Value props
Prop	Type	Default
`children`The text, or a function of the current slide, the current page and the page count.	`React.ReactNode \| ((state: CarouselValueState) => React.ReactNode)`	`—`

Viewport`Carousel.Viewport`

The scroll container that holds the slides, and the carousel's live region. Renders a <div>.

Viewport props
Prop	Type	Default
`renderBeforeHydration`Whether to render an inline script that scrolls to the initial slide before React hydrates,	`boolean`	`false`

Viewport data attributes
Data attribute	Description
`data-orientation`	The axis the slides scroll on.
`data-scrolling`	Present while the Viewport is scrolling.
`data-dragging`	Present while a mouse drag is in progress.

Shared props

Every part that renders an element takes these.

Shared props
Prop	Type
`className`CSS class applied to the element, or a function that returns a class based on the component's state.	`string \| ((state: State) => string \| undefined)`
`style`Style applied to the element, or a function that returns a style object based on the component's state.	`React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined)`
`render`Allows you to replace the component's HTML element with a different tag, or compose it with another component.	`React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, State>`

Keyboard and accessibility

Keyboard

Keyboard
Keys	Does	Part
`EnterSpace`	Presses Previous or Next; focus stays on the button	Next
`Tab`	Moves from Next into the current slide, never into a slide out of view	Slide
`Tab`	Reaches the tab of the current page, the list's one Tab stop	Tab
`ArrowLeftArrowRight`	Move focus to the previous or next tab and show its page, wrapping at both ends	TabList
`ArrowLeftArrowRight`	Are mirrored in a right-to-left layout	TabList
`ArrowUpArrowDown`	Move between the tabs when `orientation` is vertical	TabList
`HomeEnd`	Show the first or the last page	TabList
`EnterSpace`	Stops or starts the rotation; the button's name switches	AutoplayControl
`Tab`	Keyboard focus inside stops the rotation; leaving does not restart it	Root

Accessibility

What the parts set
Part	Sets	So that
Root	`role="region"` with the role description "carousel", named by `aria-label` or `aria-labelledby` (a development warning without one); `role="group"` from the app replaces it	the carousel is a landmark with its name, said as a carousel
Slide	`role="group"` with the role description "slide" and the name "3 of 5"; with a TabList, `role="tabpanel"` without a role description and the same name	each slide says where it is; the tab panels are not given a second role
Slide	`inert` on a slide with no part in view, decided when a scroll settles and never on a slide that holds focus	Tab, find and the reading order reach only what is shown
Viewport	`aria-live="off"` while rotating and `polite` otherwise, `aria-busy="true"` while scrolling, an `id` the controls point to	a slide the reader brings in is announced once, and rotation is not read out every few seconds
Previous	a `button` named "Previous slide" unless it has text or `aria-label`, `aria-controls` the Viewport; on the first page `aria-disabled` and still focusable	focus is not lost when the button stops working
Next	the same, named "Next slide", disabled on the last page	as Previous
AutoplayControl	a `button` named "Stop automatic slide show" while rotating and "Start automatic slide show" otherwise, with no `aria-pressed`	the name says what a press does; moving content can be stopped (WCAG 2.2.2)
TabList	`role="tablist"` named "Choose slide to display", one Tab stop, `aria-orientation="vertical"` when vertical	the pages are one control, crossed with the arrow keys
Tab	`role="tab"`, `aria-selected` on the current page, `aria-controls` the page's slides, named "Slide 2" or "Slides 4 to 6" unless it has text	each tab says which slides it shows
Value	the text "2 of 5", not a live region	the position can be shown without being announced twice

Focus order

In document order. The examples follow the pattern's order: the AutoplayControl first, then Previous and Next, then the current slide's content, then the tab of the current page. Nothing takes focus on mount.
Previous and Next keep focus when they scroll, and when they are disabled at either end.
Slides out of view are skipped until they scroll in; with offscreenSlides="interactive" every slide's content is reachable and the browser scrolls a focused one into view.
The TabList is one Tab stop: the tab of the current page, or the tab that last had focus while focus stays in the list.