> Leaf UI 0.8.1 · Package: @ifhover/leaf-ui · Source: 435bab23cad7d343653d9b63b049c0b0601eeefb
> Browser documentation: https://ifhover.github.io/leaf-ui/en/components/carousel.html

> For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/en/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/en/llms-full.txt.

# Carousel

Browse images or content one slide at a time.

## Basic usage


PlanCreateShare

1 / 3

basic.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/carousel/basic.tsx"
import { Carousel } from '@ifhover/leaf-ui';

const slides = [
  { key: 'plan', zh: '计划', en: 'Plan', color: '#edf6ee' },
  { key: 'create', zh: '创作', en: 'Create', color: '#eef3ff' },
  { key: 'share', zh: '分享', en: 'Share', color: '#fff5df' },
];

export function CarouselBasic() {
  return (
    <Carousel aria-label={'Project stages'}>
      {slides.map((slide) => (
        <div
          key={slide.key}
          style={{
            display: 'grid',
            placeItems: 'center',
            height: 180,
            background: slide.color,
            color: '#24372c',
            fontSize: 24,
          }}
        >
          {slide.en}
        </div>
      ))}
    </Carousel>
  );
}
```

Expand code

## Autoplay


PlanCreateShare

1 / 3

basic.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/carousel/basic.tsx"
import { Carousel } from '@ifhover/leaf-ui';

const slides = [
  { key: 'plan', zh: '计划', en: 'Plan', color: '#edf6ee' },
  { key: 'create', zh: '创作', en: 'Create', color: '#eef3ff' },
  { key: 'share', zh: '分享', en: 'Share', color: '#fff5df' },
];

export function CarouselAutoplay() {
  return (
    <Carousel autoplay={5000} arrows={false} aria-label={'Highlights'}>
      {slides.map((slide) => (
        <div
          key={slide.key}
          style={{
            display: 'grid',
            placeItems: 'center',
            height: 150,
            background: slide.color,
            color: '#24372c',
          }}
        >
          {slide.en}
        </div>
      ))}
    </Carousel>
  );
}
```

Expand code

## CarouselHandle

| Property   | Type                      | Default | Description                        |
| ---------- | ------------------------- | ------- | ---------------------------------- |
| `goTo`     | `(index: number) => void` | —       | Required. Go to a slide index.     |
| `next`     | `() => void`              | —       | Required. Go to the next item.     |
| `previous` | `() => void`              | —       | Required. Go to the previous item. |

## Carousel API

| Property             | Type                      | Default | Description                                                  |
| -------------------- | ------------------------- | ------- | ------------------------------------------------------------ |
| `activeIndex`        | `number`                  | —       | Controlled slide index.                                      |
| `defaultActiveIndex` | `number`                  | `0`     | Initial slide index.                                         |
| `onChange`           | `(index: number) => void` | —       | Called when the value changes.                               |
| `arrows`             | `boolean`                 | `true`  | Show previous and next controls.                             |
| `dots`               | `boolean`                 | `true`  | Show slide indicators.                                       |
| `autoplay`           | `boolean \| number`       | `false` | Enable autoplay; a number sets the interval in milliseconds. |
| `infinite`           | `boolean`                 | `true`  | Allow cycling through slides.                                |
| `pauseOnHover`       | `boolean`                 | `true`  | Pause on hover; focus also pauses playback.                  |

## Types and interaction

Import the props and data types when creating reusable configuration.

```ts
import type { CarouselHandle, CarouselProps } from '@ifhover/leaf-ui';
```

Provide accessible labels for icon-only actions. Interactive controls support keyboard navigation and respect ConfigProvider themes and reduced motion.