# Carousel

> Source: https://design.nanatec.co.ke/components/carousel/
> A scroll-snap carousel. Compose it from `nana-carousel-item` slides and pick the navigation, layout and behaviour through attributes — one element covers basic, multi-item, card, gallery, hero and testimonial use-cases. Built on the native scroll container, so touch swipe, trackpad and momentum work for free; mouse drag, keyboard, autoplay and looping are layered on top.

A scroll-snap carousel. Compose it from `nana-carousel-item` slides and pick the navigation, layout and behaviour through attributes — one element covers basic, multi-item, card, gallery, hero and testimonial use-cases. Built on the native scroll container, so touch swipe, trackpad and momentum work for free; mouse drag, keyboard, autoplay and looping are layered on top.

## Preview

```html
<nana-carousel style="width:100%">
  <nana-carousel-item><img src="https://picsum.photos/seed/a/800/400" alt="Slide A" style="width:100%;display:block"></nana-carousel-item>
  <nana-carousel-item><img src="https://picsum.photos/seed/b/800/400" alt="Slide B" style="width:100%;display:block"></nana-carousel-item>
</nana-carousel>
```

## Installation

```bash
npm install @nana-tec/ui-components
```

## Import

```js
import "@nana-tec/ui-components/carousel";
```

## Basic usage

```html
<nana-carousel style="width:100%">
  <nana-carousel-item><img src="https://picsum.photos/seed/a/800/400" alt="Slide A" style="width:100%;display:block"></nana-carousel-item>
  <nana-carousel-item><img src="https://picsum.photos/seed/b/800/400" alt="Slide B" style="width:100%;display:block"></nana-carousel-item>
</nana-carousel>
```

## Navigation

The `navigation` attribute controls the controls — `arrows`, `dots`,
`progress`, `numbers`, or a space-separated combo. Add `loop` to wrap around.

```html
<nana-carousel navigation="arrows dots" loop style="width:100%">
  <nana-carousel-item><img src="https://picsum.photos/seed/c/800/400" alt="Slide 1" style="width:100%;display:block"></nana-carousel-item>
  <nana-carousel-item><img src="https://picsum.photos/seed/d/800/400" alt="Slide 2" style="width:100%;display:block"></nana-carousel-item>
  <nana-carousel-item><img src="https://picsum.photos/seed/e/800/400" alt="Slide 3" style="width:100%;display:block"></nana-carousel-item>
</nana-carousel>
```

## Multi-item & peek

Show several slides at once with `slides-per-view`, and hint the next slide with
`peek`.

```html
<nana-carousel slides-per-view="3" peek navigation="arrows dots" loop style="width:100%">
  <nana-carousel-item><img src="https://picsum.photos/seed/f/400/300" alt="Item 1" style="width:100%;display:block"></nana-carousel-item>
  <nana-carousel-item><img src="https://picsum.photos/seed/g/400/300" alt="Item 2" style="width:100%;display:block"></nana-carousel-item>
  <nana-carousel-item><img src="https://picsum.photos/seed/h/400/300" alt="Item 3" style="width:100%;display:block"></nana-carousel-item>
  <nana-carousel-item><img src="https://picsum.photos/seed/i/400/300" alt="Item 4" style="width:100%;display:block"></nana-carousel-item>
  <nana-carousel-item><img src="https://picsum.photos/seed/j/400/300" alt="Item 5" style="width:100%;display:block"></nana-carousel-item>
</nana-carousel>
```

## API

## Events

| Event | Type | Description |
|---|---|---|
| `nana-slide-change` | `CustomEvent` | Fired when the active slide changes (`detail.index`, `detail.total`) |

## Slots

| Slot | Description |
|---|---|
| `(default)` | One or more `nana-carousel-item` slides |
| `error` | Custom error content (shown when `error` is set) |

## CSS Variables

| Variable | Default | Description |
|---|---|---|
| `--nana-carousel-gap` | — | Gap between slides |
| `--nana-carousel-radius` | — | Viewport corner radius |
| `--nana-carousel-accent` | — | Active dot / progress colour |
| `--nana-carousel-peek` | — | How much of the neighbour peeks (peek mode) |
| `--nana-carousel-height` | — | Viewport height (vertical orientation) |

## CSS Parts

| Part | Description |
|---|---|
| `base` | The outer container |
| `viewport` | The scrolling track |
| `nav-prev` | The previous-slide button |
| `nav-next` | The next-slide button |
| `pagination` | The dots / numbers / progress row |

## Accessibility

<ul class="a11y-grid not-content">
  <li>Keyboard accessible</li>
  <li>Screen-reader labels</li>
  <li>Focus-visible states</li>
  <li>ARIA roles and states</li>
  <li>WCAG 2.2 AA contrast</li>
</ul>

## Related components

<ul class="related not-content">
  <li><a href="/components/table/">Table</a></li>
  <li><a href="/components/carousel-item/">Carousel Item</a></li>
  <li><a href="/components/image-comparer/">Image Comparer</a></li>
  <li><a href="/components/qr-code/">QR Code</a></li>
  <li><a href="/components/icon/">Icon</a></li>
</ul>

## Storybook

See every state and prop interactively in Storybook: https://storybook.nanatec.co.ke/?path=/docs/components-carousel--docs