# Carousel

> Slides through a row of cards, such as the latest releases.

A carousel shows a row of cards that people slide through, such as the latest releases or highlights on a home screen.

## When to use

- Use it for content that people may skip, such as releases or highlights.
- Never put required information in it: what sits off screen may never be seen.
- Never autoplay.
- Show the edge of the next card, so people can tell there is more.

_Live preview of the React and Vue versions: https://design.sosialoka.tech/components/carousel/_

## Anatomy

1. Current slide
2. Next slide, partly shown
3. Position dots

Cards in a row, 16px apart, with square `outline` previous and next buttons (not pills) that turn off at the ends. On phones the buttons hide and people swipe; the page never scrolls sideways.

On phones, `CarouselDots` under the row may show where people are, since they swipe and see no buttons:

- One dot per stop: 6px, `radius-full`, 4px apart, centered 12px under the cards.
- The current slide's dot is 20px wide in `primary`; the others are `input`.
- Use dots for up to 5 slides. With more, leave them out.
- Dots only show the position. They are not buttons, and screen readers skip them.

## Props

| React | Vue | Flutter | Type | Default | Use |
| --- | --- | --- | --- | --- | --- |
| `opts` | `:opts` | `PageController(viewportFraction: 0.85)` | Embla options | none | Such as `{ align: "start" }`. |
| `CarouselItem aria-label` | same | `Semantics label` | text | none | The slide's position, such as "1 dari 5". |
| `CarouselPrevious label`, `CarouselNext label` | same | `Semantics label` | text | `Previous slide`, `Next slide` | The buttons' names, such as "Sebelumnya". |
| `CarouselDots max` | `CarouselDots :max` | dots row (see the Flutter code) | number | `5` | Position dots for phones; with more stops than this they don't show. |
| `setApi` | `@init-api` | the controller | function | none | Reads or moves the carousel from outside. |

## Code

**React**
```tsx
import { MusicIcon } from "lucide-react"
import { Carousel, CarouselContent, CarouselDots, CarouselItem, CarouselNext, CarouselPrevious } from "@/components/ui/carousel"

const releases = [
  { title: "Senja di Kota", artist: "Rara Senandika" },
  { title: "Kaset Pertama", artist: "Bima Laras" },
  { title: "Pulang Sore", artist: "Nada Kirana" },
  { title: "Hujan Bulan Juni", artist: "Arka Wening" },
  { title: "Lampu Kota", artist: "Sinta Maharani" },
]

export default function CarouselDemo() {
  return (
    <Carousel aria-label="Rilis terbaru" opts={{ align: "start" }} className="w-full max-w-md sm:mx-12">
      <CarouselContent>
        {releases.map((r, i) => (
          <CarouselItem key={r.title} aria-label={`${i + 1} dari ${releases.length}`} className="basis-2/3 sm:basis-1/2">
            <div className="flex flex-col gap-2">
              <div className="flex aspect-square items-center justify-center rounded-lg bg-muted">
                <MusicIcon aria-hidden="true" className="size-6 text-muted-foreground" />
              </div>
              <div className="text-sm">
                <p className="truncate font-medium">{r.title}</p>
                <p className="truncate text-muted-foreground">{r.artist}</p>
              </div>
            </div>
          </CarouselItem>
        ))}
      </CarouselContent>
      <CarouselPrevious label="Sebelumnya" />
      <CarouselNext label="Berikutnya" />
      <CarouselDots />
    </Carousel>
  )
}
```

**Vue**
```vue
<script setup lang="ts">
import { Music } from "@lucide/vue"
import { Carousel, CarouselContent, CarouselDots, CarouselItem, CarouselNext, CarouselPrevious } from "@/components/ui/carousel"

const releases = [
  { title: "Senja di Kota", artist: "Rara Senandika" },
  { title: "Kaset Pertama", artist: "Bima Laras" },
  { title: "Pulang Sore", artist: "Nada Kirana" },
  { title: "Hujan Bulan Juni", artist: "Arka Wening" },
  { title: "Lampu Kota", artist: "Sinta Maharani" },
]
</script>

<template>
  <Carousel aria-label="Rilis terbaru" :opts="{ align: 'start' }" class="w-full max-w-md sm:mx-12">
    <CarouselContent>
      <CarouselItem v-for="(r, i) in releases" :key="r.title" :aria-label="`${i + 1} dari ${releases.length}`" class="basis-2/3 sm:basis-1/2">
        <div class="flex flex-col gap-2">
          <div class="flex aspect-square items-center justify-center rounded-lg bg-muted">
            <Music aria-hidden="true" class="size-6 text-muted-foreground" />
          </div>
          <div class="text-sm">
            <p class="truncate font-medium">
              {{ r.title }}
            </p>
            <p class="truncate text-muted-foreground">
              {{ r.artist }}
            </p>
          </div>
        </div>
      </CarouselItem>
    </CarouselContent>
    <CarouselPrevious label="Sebelumnya" />
    <CarouselNext label="Berikutnya" />
    <CarouselDots />
  </Carousel>
</template>
```

**Flutter**
```dart
// A PageView that shows a peek of the next card. Wide screens get previous and next buttons with a "2 dari 5"
// count; phones, where people swipe, get position dots instead (hidden from screen readers, as each slide says
// its own position).
import 'package:flutter/widgets.dart';
import 'package:shadcn_ui/shadcn_ui.dart';

const _releases = [
  (title: 'Senja di Kota', artist: 'Rara Senandika'),
  (title: 'Kaset Pertama', artist: 'Bima Laras'),
  (title: 'Pulang Sore', artist: 'Nada Kirana'),
  (title: 'Hujan Bulan Juni', artist: 'Arka Wening'),
  (title: 'Lampu Kota', artist: 'Sinta Maharani'),
];

class CarouselDemo extends StatefulWidget {
  const CarouselDemo({super.key});

  @override
  State<CarouselDemo> createState() => _CarouselDemoState();
}

class _CarouselDemoState extends State<CarouselDemo> {
  final controller = PageController(viewportFraction: 0.85);
  int page = 0;

  @override
  void dispose() {
    controller.dispose();
    super.dispose();
  }

  void go(int to) =>
      controller.animateToPage(to, duration: const Duration(milliseconds: 300), curve: Curves.easeOutCubic);

  @override
  Widget build(BuildContext context) {
    final theme = ShadTheme.of(context);
    final phone = MediaQuery.sizeOf(context).width < 640;
    return ConstrainedBox(
      constraints: const BoxConstraints(maxWidth: 448),
      child: Column(
        mainAxisSize: MainAxisSize.min,
        children: [
          SizedBox(
            height: 240,
            child: PageView.builder(
              controller: controller,
              itemCount: _releases.length,
              onPageChanged: (value) => setState(() => page = value),
              itemBuilder: (context, i) => Semantics(
                container: true,
                label: '${i + 1} dari ${_releases.length}',
                child: Padding(
                  padding: const EdgeInsets.symmetric(horizontal: 6),
                  child: Column(
                    crossAxisAlignment: CrossAxisAlignment.start,
                    children: [
                      Expanded(
                        child: Container(
                          decoration: BoxDecoration(
                            color: theme.colorScheme.muted,
                            borderRadius: BorderRadius.circular(8),
                          ),
                          alignment: Alignment.center,
                          child: Icon(LucideIcons.music, color: theme.colorScheme.mutedForeground),
                        ),
                      ),
                      const SizedBox(height: 8),
                      Text(_releases[i].title, style: const TextStyle(fontWeight: FontWeight.w500)),
                      Text(_releases[i].artist, style: theme.textTheme.muted),
                    ],
                  ),
                ),
              ),
            ),
          ),
          const SizedBox(height: 12),
          if (phone)
            ExcludeSemantics(
              child: Row(
                mainAxisAlignment: MainAxisAlignment.center,
                spacing: 4,
                children: [
                  for (var i = 0; i < _releases.length; i++)
                    AnimatedContainer(
                      key: ValueKey('dot-$i'),
                      duration: const Duration(milliseconds: 200),
                      width: i == page ? 20 : 6,
                      height: 6,
                      decoration: BoxDecoration(
                        color: i == page ? theme.colorScheme.primary : theme.colorScheme.input,
                        borderRadius: BorderRadius.circular(3),
                      ),
                    ),
                ],
              ),
            )
          else
          Row(
            mainAxisAlignment: MainAxisAlignment.center,
            children: [
              Semantics(
                label: 'Sebelumnya',
                button: true,
                // excludeSemantics hides the button's own state, so say here whether it is on.
                enabled: page > 0,
                excludeSemantics: true,
                child: ShadIconButton.outline(
                  icon: const Icon(LucideIcons.chevronLeft, size: 16),
                  onPressed: page == 0 ? null : () => go(page - 1),
                ),
              ),
              const SizedBox(width: 12),
              Text('${page + 1} dari ${_releases.length}', style: theme.textTheme.muted),
              const SizedBox(width: 12),
              Semantics(
                label: 'Berikutnya',
                button: true,
                enabled: page < _releases.length - 1,
                excludeSemantics: true,
                child: ShadIconButton.outline(
                  icon: const Icon(LucideIcons.chevronRight, size: 16),
                  onPressed: page == _releases.length - 1 ? null : () => go(page + 1),
                ),
              ),
            ],
          ),
        ],
      ),
    );
  }
}
```

## Install

**React**
```bash
npx shadcn@latest add https://design.sosialoka.tech/r/react/carousel.json
```

**Vue**
```bash
npx shadcn-vue@latest add https://design.sosialoka.tech/r/vue/carousel.json
```

## Accessibility

- The carousel is a region with `aria-roledescription="carousel"`; give it a name, such as "Rilis terbaru".
- Each slide is a group with `aria-roledescription="slide"` and a label such as "1 dari 5".
- The previous and next buttons are named and turn off at the ends.
- Dots are `aria-hidden`; the slide labels, such as "1 dari 3", carry the position.
- Left and right arrow keys move between slides while focus is inside.
