React Carousel: examples and API

Preview

Live preview

Changes apply to this preview only.

Width adapts to the available space

"use client";

import {
  Carousel,
  Card,
  Image,
  CardHeader,
  CardTitle,
  Badge,
  CardDescription,
  CardContent,
  Button
} from "@pimolu/react";

const products = [
  {
    name: "Pimolu Studio",
    price: "€49",
    description: "Tokens, themes and a component gallery for product teams.",
  },
  {
    name: "Pimolu Native",
    price: "€39",
    description: "Cross-platform primitives with the same visual contract.",
  },
  {
    name: "Pimolu Icons",
    price: "€19",
    description: "A consistent icon set tuned for every preset.",
  },
];

export function DemoExample() {
  return (
    <Carousel aria-label="Product gallery" loop showDots>
      {
        products.map((product) => (<Card key={product.name}>
          <Image
            src="/images/pimolu-studio.webp"
            alt={`${product.name} cover`}
            aspectRatio={16 / 9}
            fit="cover"
            rounded="none"
            width={400}
            height={300}
          />
          <CardHeader>
            <div
              className="flex flex-wrap items-center gap-3 min-w-0 justify-between"
            >
              <CardTitle>
                {product.name}
              </CardTitle>
              <Badge variant="secondary">
                {product.price}
              </Badge>
            </div>
            <CardDescription>
              {product.description}
            </CardDescription>
          </CardHeader>
          <CardContent>
            <Button size="sm">View product</Button>
          </CardContent>
        </Card>))
      }
    </Carousel>
  );
}

More examples

Different configurations and compositions using the real Pimolu API. Each preview runs independently and follows the site appearance.

Basic

Three slides, controls and dots. The previous button is disabled on the first slide until loop is enabled.

Open preview

Autoplay and loop

Autoplay pauses while the pointer or keyboard focus is inside, from the pause control, and stays still when the user prefers reduced motion.

Open preview

Controlled

The parent owns the index and receives every navigation, including clicks on the dots.

Open preview

Usage

Keep navigation explicit; autoplay must be optional and pauseable when enabled.

API reference

Generated from the public TypeScript declarations. Native HTML attributes are inherited where the component extends them; this reference includes Pimolu props and selected common native attributes.

PimoluCarouselLabels

Type source

PimoluCarouselLabels public API
Name	Type	Default	Description
`previous`Required	`string`	—	Accessible name of the previous control.
`next`Required	`string`	—	Accessible name of the next control.
`pause`Required	`string`	—	Accessible name of the pause control.
`play`Required	`string`	—	Accessible name of the play control.
`pagination`Required	`string`	—	Accessible name of the dot list.
`slide`Required	`(index: number, total: number) => string`	—	Accessible name of a slide, for example "2 of 4".
`goToSlide`Required	`(index: number, total: number) => string`	—	Accessible name of a dot, for example "Go to slide 2".

previousRequired: string
No default extracted.
Accessible name of the previous control.
nextRequired: string
No default extracted.
Accessible name of the next control.
pauseRequired: string
No default extracted.
Accessible name of the pause control.
playRequired: string
No default extracted.
Accessible name of the play control.
paginationRequired: string
No default extracted.
Accessible name of the dot list.
slideRequired: (index: number, total: number) => string
No default extracted.
Accessible name of a slide, for example "2 of 4".
goToSlideRequired: (index: number, total: number) => string
No default extracted.
Accessible name of a dot, for example "Go to slide 2".

PimoluCarouselProps

Type source

PimoluCarouselProps public API
Name	Type	Default	Description
`children`Required	`ReactNode`	—	Slides. Each direct child becomes one scroll-snapped slide.
`index`	`number \| undefined`	—	Controlled active index (zero-based).
`defaultIndex`	`number \| undefined`	`0`	Initial index when uncontrolled. Defaults to 0.
`onIndexChange`	`((index: number) => void) \| undefined`	—	Called with the new index when navigation changes it.
`autoPlay`	`boolean \| undefined`	`false`	Advances automatically. Defaults to false.
`interval`	`number \| undefined`	`5000`	Autoplay delay in milliseconds. Defaults to 5000.
`loop`	`boolean \| undefined`	`false`	Wraps from the last slide to the first one. Defaults to false.
`showControls`	`boolean \| undefined`	`true`	Shows the previous and next buttons. Defaults to true.
`showDots`	`boolean \| undefined`	`true`	Shows the pagination dots. Defaults to true.
`showPauseControl`	`boolean \| undefined`	`true`	Shows a pause/play control while autoplay is enabled. Defaults to true.
`pauseOnHover`	`boolean \| undefined`	`true`	Pauses autoplay while the pointer hovers the carousel or focus is inside it. Defaults to true.
`labels`	`Partial<PimoluCarouselLabels> \| undefined`	—	Overrides the built-in accessible labels.
`viewportClassName`	`string \| undefined`	—	Class applied to the scroll viewport.
`slideClassName`	`string \| undefined`	—	Class applied to every slide wrapper.
`defaultValue`	`string \| number \| readonly string[] \| undefined`	—	Standard React/HTML attribute.
`className`	`string \| undefined`	—	Standard React/HTML attribute.
`style`	`CSSProperties \| undefined`	—	Standard React/HTML attribute.
`aria-label`	`string \| undefined`	—	Defines a string value that labels the current element.
`onClick`	`MouseEventHandler<HTMLDivElement> \| undefined`	—	Standard React/HTML attribute.

childrenRequired: ReactNode
No default extracted.
Slides. Each direct child becomes one scroll-snapped slide.
index: number | undefined
No default extracted.
Controlled active index (zero-based).
defaultIndex: number | undefined
Default: 0
Initial index when uncontrolled. Defaults to 0.
onIndexChange: ((index: number) => void) | undefined
No default extracted.
Called with the new index when navigation changes it.
autoPlay: boolean | undefined
Default: false
Advances automatically. Defaults to false.
interval: number | undefined
Default: 5000
Autoplay delay in milliseconds. Defaults to 5000.
loop: boolean | undefined
Default: false
Wraps from the last slide to the first one. Defaults to false.
showControls: boolean | undefined
Default: true
Shows the previous and next buttons. Defaults to true.
showDots: boolean | undefined
Default: true
Shows the pagination dots. Defaults to true.
showPauseControl: boolean | undefined
Default: true
Shows a pause/play control while autoplay is enabled. Defaults to true.
pauseOnHover: boolean | undefined
Default: true
Pauses autoplay while the pointer hovers the carousel or focus is inside it. Defaults to true.
labels: Partial<PimoluCarouselLabels> | undefined
No default extracted.
Overrides the built-in accessible labels.
viewportClassName: string | undefined
No default extracted.
Class applied to the scroll viewport.
slideClassName: string | undefined
No default extracted.
Class applied to every slide wrapper.
defaultValue: string | number | readonly string[] | undefined
No default extracted.
Standard React/HTML attribute.
className: string | undefined
No default extracted.
Standard React/HTML attribute.
style: CSSProperties | undefined
No default extracted.
Standard React/HTML attribute.
aria-label: string | undefined
No default extracted.
Defines a string value that labels the current element.
onClick: MouseEventHandler<HTMLDivElement> | undefined
No default extracted.
Standard React/HTML attribute.

Accessibility

Test previous/next and slide announcements, and respect reduced-motion preferences.

Read the accessibility guide →

Preview

Pimolu Studio

Pimolu Native

Pimolu Icons

More examples

Basic

Autoplay and loop

Controlled

Usage

API reference

PimoluCarouselLabels

PimoluCarouselProps

Accessibility

Related components