# Carousel

> A slideshow component for cycling through elements—images or slides of text—like a carousel.

Source: https://bootstrap-svelte.vercel.app/components/carousel — part of the Bootstrap Svelte documentation (index: https://bootstrap-svelte.vercel.app/llms.txt).

## Basic Example

Here's a basic carousel with slides only.

![Slide 1](https://placehold.co/800x400/777/555?text=Slide+1)

```html
<Carousel.Root animation="none">
    <Carousel.Inner>
        <Carousel.Item isActive={true}>
            <img src="https://placehold.co/800x400/777/555?text=Slide+1" class="d-block w-100" alt="Slide 1" />
        </Carousel.Item>
        <Carousel.Item>
            <img src="https://placehold.co/800x400/777/555?text=Slide+2" class="d-block w-100" alt="Slide 2" />
        </Carousel.Item>
        <Carousel.Item>
            <img src="https://placehold.co/800x400/777/555?text=Slide+3" class="d-block w-100" alt="Slide 3" />
        </Carousel.Item>
    </Carousel.Inner>
    <Carousel.ControlPrev />
    <Carousel.ControlNext />
</Carousel.Root>
```

## With Controls

Adding previous and next controls with Carousel.ControlPrev and Carousel.ControlNext components.

![Slide 1](https://placehold.co/800x400/777/555?text=Slide+1)

```html
<Carousel.Root animation="slide">
    <Carousel.Inner>
        <Carousel.Item isActive={true}>
            <img src="https://placehold.co/800x400/777/555?text=Slide+1" class="d-block w-100" alt="Slide 1" />
        </Carousel.Item>
        <Carousel.Item>
            <img src="https://placehold.co/800x400/777/555?text=Slide+2" class="d-block w-100" alt="Slide 2" />
        </Carousel.Item>
        <Carousel.Item>
            <img src="https://placehold.co/800x400/777/555?text=Slide+3" class="d-block w-100" alt="Slide 3" />
        </Carousel.Item>
    </Carousel.Inner>
    <Carousel.ControlPrev />
    <Carousel.ControlNext />
</Carousel.Root>
```

## With Indicators

You can also add the indicators to the carousel with Carousel.Indicators and Carousel.IndicatorButton components.

![Slide 1](https://placehold.co/800x400/777/555?text=Slide+1)

```html
<Carousel.Root animation="slide">
    <Carousel.Indicators>
        <Carousel.IndicatorButton ariaLabel="Slide 1" />
        <Carousel.IndicatorButton ariaLabel="Slide 2" />
        <Carousel.IndicatorButton ariaLabel="Slide 3" />
    </Carousel.Indicators>
    <Carousel.Inner>
        <Carousel.Item isActive={true}>
            <img src="https://placehold.co/800x400/777/555?text=Slide+1" class="d-block w-100" alt="Slide 1" />
        </Carousel.Item>
        <Carousel.Item>
            <img src="https://placehold.co/800x400/777/555?text=Slide+2" class="d-block w-100" alt="Slide 2" />
        </Carousel.Item>
        <Carousel.Item>
            <img src="https://placehold.co/800x400/777/555?text=Slide+3" class="d-block w-100" alt="Slide 3" />
        </Carousel.Item>
    </Carousel.Inner>
    <Carousel.ControlPrev />
    <Carousel.ControlNext />
</Carousel.Root>
```

## With Captions

Add captions to your slides with the Carousel.Caption component.

![Slide 1](https://placehold.co/800x400/777/555?text=Slide+1)

##### First slide label

Some representative placeholder content for the first slide.

```html
<Carousel.Root animation="slide">
    <Carousel.Indicators>
        <Carousel.IndicatorButton ariaLabel="Slide 1" />
        <Carousel.IndicatorButton ariaLabel="Slide 2" />
        <Carousel.IndicatorButton ariaLabel="Slide 3" />
    </Carousel.Indicators>
    <Carousel.Inner>
        <Carousel.Item isActive={true}>
            <img src="https://placehold.co/800x400/777/555?text=Slide+1" class="d-block w-100" alt="Slide 1" />
            <Carousel.Caption>
                <h5>First slide label</h5>
                <p>Some representative placeholder content for the first slide.</p>
            </Carousel.Caption>
        </Carousel.Item>
        <Carousel.Item>
            <img src="https://placehold.co/800x400/777/555?text=Slide+2" class="d-block w-100" alt="Slide 2" />
            <Carousel.Caption>
                <h5>Second slide label</h5>
                <p>Some representative placeholder content for the second slide.</p>
            </Carousel.Caption>
        </Carousel.Item>
        <Carousel.Item>
            <img src="https://placehold.co/800x400/777/555?text=Slide+3" class="d-block w-100" alt="Slide 3" />
            <Carousel.Caption>
                <h5>Third slide label</h5>
                <p>Some representative placeholder content for the third slide.</p>
            </Carousel.Caption>
        </Carousel.Item>
    </Carousel.Inner>
    <Carousel.ControlPrev />
    <Carousel.ControlNext />
</Carousel.Root>
```

## Fade

Add `animation="fade"` to your carousel to animate slides with a fade transition where the old slide will fade out before the new one fades in.

![Slide 1](https://placehold.co/800x400/777/555?text=Slide+1)

```html
<Carousel.Root animation="fade">
    <Carousel.Inner>
        <Carousel.Item isActive={true}>
            <img src="https://placehold.co/800x400/777/555?text=Slide+1" class="d-block w-100" alt="Slide 1" />
        </Carousel.Item>
        <Carousel.Item>
            <img src="https://placehold.co/800x400/777/555?text=Slide+2" class="d-block w-100" alt="Slide 2" />
        </Carousel.Item>
        <Carousel.Item>
            <img src="https://placehold.co/800x400/777/555?text=Slide+3" class="d-block w-100" alt="Slide 3" />
        </Carousel.Item>
    </Carousel.Inner>
    <Carousel.ControlPrev />
    <Carousel.ControlNext />
</Carousel.Root>
```

## Crossfade

Add `animation="crossfade"` to your carousel to animate slides with a fade transition instead of a slide.

![Slide 1](https://placehold.co/800x400/777/555?text=Slide+1)

```html
<Carousel.Root animation="crossfade">
    <Carousel.Inner>
        <Carousel.Item isActive={true}>
            <img src="https://placehold.co/800x400/777/555?text=Slide+1" class="d-block w-100" alt="Slide 1" />
        </Carousel.Item>
        <Carousel.Item>
            <img src="https://placehold.co/800x400/777/555?text=Slide+2" class="d-block w-100" alt="Slide 2" />
        </Carousel.Item>
        <Carousel.Item>
            <img src="https://placehold.co/800x400/777/555?text=Slide+3" class="d-block w-100" alt="Slide 3" />
        </Carousel.Item>
    </Carousel.Inner>
    <Carousel.ControlPrev />
    <Carousel.ControlNext />
</Carousel.Root>
```

## Auto-playing Carousel

To make the carousel auto-play, set `ride="carousel"` on the root component. This will start the carousel automatically when the page loads.

![Slide 1](https://placehold.co/800x400/777/555?text=Slide+1)

```html
<Carousel.Root ride="carousel" animation="slide" transitionDuration={1000}>
    <Carousel.Inner>
        <Carousel.Item isActive={true}>
            <img src="https://placehold.co/800x400/777/555?text=Slide+1" class="d-block w-100" alt="Slide 1" />
        </Carousel.Item>
        <Carousel.Item>
            <img src="https://placehold.co/800x400/777/555?text=Slide+2" class="d-block w-100" alt="Slide 2" />
        </Carousel.Item>
        <Carousel.Item>
            <img src="https://placehold.co/800x400/777/555?text=Slide+3" class="d-block w-100" alt="Slide 3" />
        </Carousel.Item>
    </Carousel.Inner>
    <Carousel.ControlPrev />
    <Carousel.ControlNext />
</Carousel.Root>
```

To make the carousel auto-play after the first interaction, set `ride="true"` on the root component. It will not start the cycling of the slide until the user interacts with the carousel.

![Slide 1](https://placehold.co/800x400/777/555?text=Slide+1)

```html
<Carousel.Root ride={true} animation="slide" transitionDuration={1000}>
    <Carousel.Inner>
        <Carousel.Item isActive={true}>
            <img src="https://placehold.co/800x400/777/555?text=Slide+1" class="d-block w-100" alt="Slide 1" />
        </Carousel.Item>
        <Carousel.Item>
            <img src="https://placehold.co/800x400/777/555?text=Slide+2" class="d-block w-100" alt="Slide 2" />
        </Carousel.Item>
        <Carousel.Item>
            <img src="https://placehold.co/800x400/777/555?text=Slide+3" class="d-block w-100" alt="Slide 3" />
        </Carousel.Item>
    </Carousel.Inner>
    <Carousel.ControlPrev />
    <Carousel.ControlNext />
</Carousel.Root>
```

## Individual Interval

You can specify different intervals for each slide using the `interval` prop on Carousel.Item.

![Slide 1](https://placehold.co/800x400/777/555?text=Slide+1)

##### First slide label

This slide stays for 10 seconds.

(Cycling in 10s)

```html
<Carousel.Root animation="slide" ride="carousel">
    <Carousel.Inner>
        <Carousel.Item
            isActive={true}
            interval={10000}
            onSlide={() => { carouselItemDelay = 10000; startCountdown(); }}>
            <img src="https://placehold.co/800x400/777/555?text=Slide+1" class="d-block w-100" alt="Slide 1" />
            <Carousel.Caption>
                <h5>First slide label</h5>
                <p>This slide stays for 10 seconds.</p>
                <span>(Cycling in {countdownSeconds}s)</span>
            </Carousel.Caption>
        </Carousel.Item>
        <Carousel.Item
            interval={2000}
            onSlide={() => { carouselItemDelay = 2000; startCountdown(); }}>
            <img src="https://placehold.co/800x400/777/555?text=Slide+2" class="d-block w-100" alt="Slide 2" />
            <Carousel.Caption>
                <h5>Second slide label</h5>
                <p>This slide stays for 2 seconds.</p>
                <span>(Cycling in {countdownSeconds}s)</span>
            </Carousel.Caption>
        </Carousel.Item>
        <Carousel.Item onSlide={() => { carouselItemDelay = 5000; startCountdown(); }}>
            <img src="https://placehold.co/800x400/777/555?text=Slide+3" class="d-block w-100" alt="Slide 3" />
            <Carousel.Caption>
                <h5>Third slide label</h5>
                <p>This slide uses the default interval of 5 seconds.</p>
                <span>(Cycling in {countdownSeconds}s)</span>
            </Carousel.Caption>
        </Carousel.Item>
    </Carousel.Inner>
    <Carousel.ControlPrev />
    <Carousel.ControlNext />
</Carousel.Root>
```

## Dark Variant

Instead of adding `.carousel-dark`, set `data-bs-theme="dark"` on the root element, a parent wrapper, or the component itself.

![Slide 1](https://placehold.co/800x400/f5f5f5/aaa?text=Slide+1)

##### First slide label

Some representative placeholder content for the first slide.

```html
<div data-bs-theme="dark">
    <Carousel.Root animation="slide">
        <Carousel.Indicators>
            <Carousel.IndicatorButton ariaLabel="Slide 1" />
            <Carousel.IndicatorButton ariaLabel="Slide 2" />
            <Carousel.IndicatorButton ariaLabel="Slide 3" />
        </Carousel.Indicators>
        <Carousel.Inner>
            <Carousel.Item isActive={true}>
                <img src="https://placehold.co/800x400/f5f5f5/aaa?text=Slide+1" class="d-block w-100" alt="Slide 1" />
                <Carousel.Caption>
                    <h5>First slide label</h5>
                    <p>Some representative placeholder content for the first slide.</p>
                </Carousel.Caption>
            </Carousel.Item>
            <Carousel.Item>
                <img src="https://placehold.co/800x400/f5f5f5/aaa?text=Slide+2" class="d-block w-100" alt="Slide 2" />
                <Carousel.Caption>
                    <h5>Second slide label</h5>
                    <p>Some representative placeholder content for the second slide.</p>
                </Carousel.Caption>
            </Carousel.Item>
            <Carousel.Item>
                <img src="https://placehold.co/800x400/f5f5f5/aaa?text=Slide+3" class="d-block w-100" alt="Slide 3" />
                <Carousel.Caption>
                    <h5>Third slide label</h5>
                    <p>Some representative placeholder content for the third slide.</p>
                </Carousel.Caption>
            </Carousel.Item>
        </Carousel.Inner>
        <Carousel.ControlPrev />
        <Carousel.ControlNext />
    </Carousel.Root>
</div>
```

## API Reference

### Carousel.Root Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `animation` | `'none' \| 'slide' \| 'fade' \| 'crossfade'` | `'none'` | Adds the 'slide' class for slide animations |
| `class` | `string` | - | Additional CSS classes to apply to the component |
| `elementRef` | `HTMLElement \| null` | `null` | Reference to the DOM element |
| `id` | `string` | Auto-generated | ID for the carousel element |
| `interval` | `number` | `5000` | Time in milliseconds to show each slide before advancing |
| `pause` | `false \| 'hover'` | `'hover'` | Sets whether to pause the carousel on hover or not |
| `ride` | `boolean \| 'carousel'` | `false` | Sets autoplay behavior. 'carousel' auto-plays on page load, 'true' auto-plays after user interaction |
| `style` | `string` | `undefined` | Additional inline styles to apply to the component |
| `transitionDuration` | `number` | `600` | Duration of the transition effect in milliseconds |

### Carousel.Item Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `class` | `string` | - | Additional CSS classes to apply to the component |
| `elementRef` | `HTMLElement \| null` | `null` | Reference to the DOM element |
| `id` | `string` | Auto-generated | ID for the carousel element |
| `isActive` | `boolean` | `false` | Makes this item the active slide |
| `interval` | `number` | `5000` | Time in milliseconds to show this slide before advancing |
| `onSlide` | `EventListener` | - | Callback function triggered when the item begins to slide |
| `onSlid` | `EventListener` | - | Callback function triggered after the item has slid |
| `style` | `string` | `undefined` | Additional inline styles to apply to the component |

### Carousel.IndicatorButton Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `ariaLabel` | `string` | `'Slide #'` | Screen reader text for accessibility |
| `class` | `string` | - | Additional CSS classes to apply to the component |
| `elementRef` | `HTMLElement \| null` | `null` | Reference to the DOM element |

### Carousel.ControlPrev/ControlNext Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `class` | `string` | - | Additional CSS classes to apply to the component |
| `elementRef` | `HTMLElement \| null` | `null` | Reference to the DOM element |

### CSS Classes

The component applies Bootstrap's carousel classes based on the provided props and sub-components:

- `carousel` - Applied to Carousel.Root
- `slide` - Applied to Carousel.Root when isSlide is true
- `carousel-fade` - Applied to Carousel.Root when isFade is true
- `carousel-dark` - Applied to Carousel.Root when isDark is true
- `carousel-inner` - Applied to Carousel.Inner
- `carousel-item` - Applied to Carousel.Item
- `active` - Applied to Carousel.Item when isActive is true
- `carousel-caption` - Applied to Carousel.Caption
- `carousel-indicators` - Applied to Carousel.Indicators
- `carousel-control-prev` - Applied to Carousel.ControlPrev
- `carousel-control-next` - Applied to Carousel.ControlNext