# SvCarousel
A slideshow: a sliding track with prev/next arrows, dot indicators, optional
autoplay that pauses on hover, and touch swipe.
`SvCarousel` renders your slides through a `slide` snippet - it hands you the
index and you return the content - so it works equally well for images, cards,
or onboarding steps. The active slide is bindable, autoplay pauses on hover and
focus, and dragging past a threshold advances the track. Colors and radius come
from the grid's `--sg-*` tokens.
Related: [SvSkeleton](https://svgrid.com/docs/help/ui-components/sv-skeleton/) · [SvAvatarGroup](https://svgrid.com/docs/help/ui-components/sv-avatar-group/) · [Feedback & display overview](https://svgrid.com/docs/help/ui-components/feedback/)
## Installation
Add it with the CLI - this drops a ready-to-edit `SvCarousel` starter into your app:
Prefer to see it first? `npx @svgrid/ui try carousel` opens it in a throwaway sandbox - no project needed.
Or install the package and import it directly. `SvCarousel` ships free in
`@svgrid/grid` (dependency-free):
The examples on this page import from `@svgrid/grid`:
```svelte
```
```ts
import { SvCarousel } from '@svgrid/grid'
```
## Example
> Live demo: Carousel & guided tour - https://svgrid.com/demos/342-carousel-tour/
```svelte
{#snippet slide(i)}{/snippet}
```
## Props
| Prop | Type | Default | Description |
| ----------- | ------------------- | ------------ | -------------------------------------------------------------- |
| `count` | `number` | - | Number of slides. The `slide` snippet is called per index. |
| `slide` | `Snippet<[number]>` | - | Renders one slide; receives the slide index. |
| `current` | `number` | `0` | Active slide index. Bindable with `bind:current`. |
| `autoplay` | `number` | `0` | Autoplay interval in ms; `0` is off. Pauses on hover/focus. |
| `loop` | `boolean` | `true` | Wraps past the ends instead of stopping. |
| `arrows` | `boolean` | `true` | Shows prev/next arrows (hidden when there is one slide). |
| `dots` | `boolean` | `true` | Shows the dot indicator row. |
| `ariaLabel` | `string` | `'Carousel'` | Accessible name for the carousel region. |
| `dir` | `EditorDir` (`ltr` \| `rtl` \| `auto`) | - | Text direction; `rtl` mirrors the arrows and slide direction. |
## Examples
### Bind the active slide
Use `bind:current` to drive or read the position from outside - handy for a
custom counter or synced controls:
```svelte
{#snippet slide(i)}{/snippet}
Slide {current + 1} of {count}
```
### Autoplay that pauses on hover
Set an interval; the carousel stops advancing while the pointer or focus is
inside, and resumes on leave:
```svelte
{#snippet slide(i)}{/snippet}
```
### Non-looping with arrows only
Turn off `loop` and `dots` for a stepped gallery where the arrows disable at the
ends:
```svelte
{#snippet slide(i)}{/snippet}
```
### An onboarding tour
Drive a stepped welcome flow with `bind:current` and a non-looping track, then
show a "Get started" button once the reader reaches the last slide:
```svelte
{#snippet slide(i)}
{steps[i].title}
{steps[i].body}
{/snippet}
{#if onLast}
Get started
{:else}
(current += 1)}>Next
{/if}
```
> Tip: leave `autoplay` off for a tour - the default `0` keeps the carousel
> still so readers move at their own pace, and the built-in arrows still work.
## Accessibility
- The region carries `role="group"`, `aria-roledescription="carousel"`, and your
`ariaLabel`; each slide is labeled "N of total" and inactive slides are
`aria-hidden`.
- Arrows and dots are real `