Carousel

Steps through slides one at a time. Swiping, keyboard navigation and RTL are all supported.

import { Carousel } from 'neba';

<Carousel label="Product highlights">
  <img src="/one.jpg" alt="" />
  <img src="/two.jpg" alt="" />
</Carousel>;

Every top-level child becomes one slide. There is no slide sub-component: the snap point, the width and the role="group" / aria-roledescription="slide" pair are added for you.

Props

Prop	Type	Default	Description
locale	string	—	BCP 47 tag: the region name, the arrows and every slide name
variantshared	'solid' | 'outline' | 'text'	'outline'	Weight of the frame, said the way a container says it: the sheet is never dyed, because a carousel holds other people’s pictures. `text` when they have edges of their own
sizeshared	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'	The frame’s radius, the arrows and how far they sit in, and the size of the dots
colorshared	'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info'	'primary'	Semantic colour role. Arbitrary colour values are not accepted
densityshared	'default' | 'compact'	'default'	Padding only: never the height, never the type scale
elevationshared	0 | 1 | 2 | 3	0	Drop shadow depth. 0 means no shadow at all
value	number	—	Which slide is showing, counted from 0
defaultValue	number	0	Which starts showing
onValueChange	(index: number) => void	—	Called when the slide changes: including when it changed because somebody swiped
loop	boolean	true	Whether the arrows wrap from the last slide back to the first. With it off they go inert at the ends instead, which is the honest thing for a set that has a beginning and an end
autoPlay	boolean	false	Advances on its own. Off by default and deliberately: a carousel that moves while it is being read is the most complained-about pattern on the web. It pauses on hover, on focus anywhere inside it, and in a background tab, and does not start at all for a reader who asked for reduced motion. Turning it on draws a button that stops it, under the frame
interval	number	5000	How long each slide is held, in milliseconds
arrows	boolean	true	The previous/next buttons
indicators	boolean	true	The row of position dots under the frame
label	string	—	The accessible name. It has a default rather than being optional: a region with no name is a region nobody can skip
previousLabel	string	—	The previous button’s name
nextLabel	string	—	The next button’s name
pauseLabel · playLabel	string	—	The rotation control's two names: while the slides are advancing, and once they have been stopped. Default to the locale's wording
slideLabel	(index: number, count: number) => string	—	How one slide is named to a screen reader, and how its dot is labelled. Defaults to the locale's wording
children	ReactNode	—	The slides. Every top-level child becomes one: the wrapper carries the snap point, the width and the roles, none of which anybody should have to put on a photograph

Every native <div> attribute passes through.

Underneath it is a scroll container with CSS scroll snapping. That is what makes swiping the browser's own behaviour, flips the direction automatically under RTL, and puts the transition on scroll-behavior: smooth. Which becomes an instant cut under prefers-reduced-motion through the same code path.

Examples

loop · arrows · indicators

Without loop, the arrows go inert at the ends, which suits a set that has a first and a last. arrows and indicators draw the side arrows and the dots beneath.

The arrows are drawn over the frame, so a slide with text near its edges should pad far enough in to clear them: about 3.5rem at size="md".

import { Carousel, Typography } from 'neba';

const COLORS = ['primary', 'success', 'warning', 'danger'] as const;

function Panel({ index }: { index: number }) {
  return (
    <div
      className="flex h-32 items-center justify-center"
      style={{ background: `var(--neba-${COLORS[index % COLORS.length]}-soft-press)` }}
    >
      <Typography level="h4">{index + 1}</Typography>
    </div>
  );
}

/**
 * The chrome is optional and the ends are a choice. Without `loop` the arrows go
 * inert at the ends rather than wrapping — which is the honest thing for a set
 * that has a first and a last.
 */
export default function CarouselOptions() {
  return (
    <div className="flex w-full flex-col gap-6">
      <div className="flex flex-col gap-2">
        <Typography level="caption">loop=&#123;false&#125;</Typography>
        <Carousel label="Not looping" loop={false} variant="text">
          {[0, 1, 2, 3].map((index) => (
            <Panel key={index} index={index} />
          ))}
        </Carousel>
      </div>

      <div className="flex flex-col gap-2">
        <Typography level="caption">arrows=&#123;false&#125; — dots and dragging only</Typography>
        <Carousel label="Dots only" arrows={false} variant="text">
          {[0, 1, 2, 3].map((index) => (
            <Panel key={index} index={index} />
          ))}
        </Carousel>
      </div>

      <div className="flex flex-col gap-2">
        <Typography level="caption">
          autoPlay — a button to stop it, and it pauses on hover, on focus and in a background tab
        </Typography>
        <Carousel label="Auto playing" autoPlay interval={2500} indicators variant="text">
          {[0, 1, 2, 3].map((index) => (
            <Panel key={index} index={index} />
          ))}
        </Carousel>
      </div>
    </div>
  );
}

Photographs

A picture fills the frame, so there is nothing to pad in and the arrows sit over the image. Each slide is one Image with a ratio, which keeps the strip one height while the files load.

import { Carousel, Image } from 'neba';

const SLIDES = [
  {
    src: '/samples/photos/alpine-lake-dawn.jpg',
    alt: 'A still alpine lake with the first light on the far ridge'
  },
  {
    src: '/samples/photos/misty-tea-terraces-sunrise.jpg',
    alt: 'Terraced tea fields under morning mist'
  },
  {
    src: '/samples/photos/rowboat-misty-pond-sunrise.jpg',
    alt: 'A rowboat moored on a misty pond at sunrise'
  },
  {
    src: '/samples/photos/frosted-pinecones-moss.jpg',
    alt: 'Frosted pine cones lying on moss'
  }
];

/**
 * The other side of the padding rule: a picture fills the frame, so there is
 * nothing to pad in, and the arrows are drawn over the photograph itself.
 */
export default function CarouselPhotos() {
  return (
    <Carousel label="Photographs" className="w-full max-w-lg" indicators>
      {SLIDES.map((slide) => (
        <Image key={slide.src} src={slide.src} alt={slide.alt} ratio="3 / 2" />
      ))}
    </Carousel>
  );
}

value and onValueChange

Controlled, the strip can be driven by something else on the page. onValueChange also fires when the slide changed because somebody swiped.

import { useState } from 'react';
import { Button, ButtonGroup, Carousel, Typography } from 'neba';

const STEPS = ['Connect a repository', 'Pick a branch', 'Choose a region', 'Deploy'];

/**
 * `value` / `onValueChange` are the usual controlled pair, so a carousel can be
 * driven by something else on the page — here, a wizard's own step buttons.
 */
export default function CarouselControlled() {
  const [step, setStep] = useState(0);

  return (
    <div className="flex w-full flex-col gap-3">
      <Carousel
        label="Setup steps"
        value={step}
        onValueChange={setStep}
        arrows={false}
        indicators={false}
        loop={false}
      >
        {STEPS.map((title, index) => (
          <div key={title} className="flex h-28 flex-col justify-center gap-1 p-6">
            <Typography level="overline">
              Step {index + 1} of {STEPS.length}
            </Typography>
            <Typography level="h4">{title}</Typography>
          </div>
        ))}
      </Carousel>

      <ButtonGroup variant="outline" size="sm" color="secondary">
        <Button disabled={step === 0} onClick={() => setStep(step - 1)}>
          Back
        </Button>
        <Button disabled={step === STEPS.length - 1} onClick={() => setStep(step + 1)}>
          Next
        </Button>
      </ButtonGroup>
    </div>
  );
}

autoPlay and interval

autoPlay is off by default. With it on, it pauses on hover, on focus anywhere inside, and in a background tab, and it does not start at all under prefers-reduced-motion. The live region announcing the current slide stays silent while it runs, and starts again once the slides are stopped.

Turning it on also draws a button that stops the rotation, in the row under the frame beside the dots. It has no prop to remove it: hover and focus are not a mechanism for a reader on a phone or a magnifier. pauseLabel and playLabel name it.

If every slide has to be read, consider Tabs or a plain vertical stack instead.

Accessibility

• label becomes the carousel's accessible name. previousLabel · nextLabel · pauseLabel · playLabel · slideLabel name the controls.
• autoPlay draws its own stop button under the frame, so the rotation can be stopped by a reader who neither hovers nor tabs.
• Each slide carries role="group" and aria-roledescription="slide".

What is not offered

• More than one slide in view: use Grid with overflow-x-auto.
• Vertical: a scrolling list already does that.
• Fade: it cannot be combined with a scroll-based implementation.
• locale decides the region name, the arrows and every slide name; label and slideLabel write them out instead.