# Carousel

> Menggeser deretan kartu, misalnya rilis terbaru.

Carousel menampilkan deretan kartu yang bisa digeser, misalnya rilis terbaru atau sorotan di layar beranda.

## Kapan dipakai

- Pakai untuk konten yang boleh terlewat, misalnya rilis atau sorotan.
- Jangan taruh informasi wajib di dalamnya: yang ada di luar layar mungkin tidak pernah terlihat.
- Jangan pakai autoplay.
- Tampilkan tepi kartu berikutnya, supaya orang tahu masih ada lagi.

_Pratinjau langsung versi React dan Vue: https://design.sosialoka.tech/id/components/carousel/_

## Anatomi

1. Slide saat ini
2. Slide berikutnya, terlihat sebagian
3. Titik posisi

Kartu berderet dengan jarak 16px, plus tombol sebelumnya dan berikutnya `outline` berbentuk kotak (bukan pil) yang nonaktif di ujung. Di HP tombolnya disembunyikan dan orang cukup menggeser; halaman tidak pernah bergulir ke samping.

Di HP, `CarouselDots` di bawah deretan kartu boleh menunjukkan posisi, karena orang menggeser tanpa melihat tombol:

- Satu titik per perhentian: 6px, `radius-full`, berjarak 4px, di tengah 12px di bawah kartu.
- Titik slide yang sedang tampil selebar 20px dengan warna `primary`; sisanya `input`.
- Pakai titik untuk maksimal 5 slide. Lebih dari itu, jangan pakai titik.
- Titik hanya menunjukkan posisi. Titik bukan tombol, dan pembaca layar melewatinya.

## Props

| React | Vue | Flutter | Tipe | Bawaan | Kegunaan |
| --- | --- | --- | --- | --- | --- |
| `opts` | `:opts` | `PageController(viewportFraction: 0.85)` | opsi Embla | tidak ada | Misalnya `{ align: "start" }`. |
| `CarouselItem aria-label` | sama | `Semantics label` | teks | tidak ada | Posisi slide, misalnya "1 dari 5". |
| `CarouselPrevious label`, `CarouselNext label` | sama | `Semantics label` | teks | `Previous slide`, `Next slide` | Nama tombol, misalnya "Sebelumnya". |
| `CarouselDots max` | `CarouselDots :max` | baris titik (lihat kode Flutter) | angka | `5` | Titik posisi untuk HP; kalau perhentiannya lebih dari ini, titik tidak tampil. |
| `setApi` | `@init-api` | controller-nya | fungsi | tidak ada | Membaca atau menggeser carousel dari luar. |

## Kode

**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),
                ),
              ),
            ],
          ),
        ],
      ),
    );
  }
}
```

## Instal

**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
```

## Aksesibilitas

- Carousel adalah region dengan `aria-roledescription="carousel"`; beri nama, misalnya "Rilis terbaru".
- Setiap slide adalah group dengan `aria-roledescription="slide"` dan label seperti "1 dari 5".
- Tombol sebelumnya dan berikutnya diberi nama dan nonaktif di ujung.
- Titik diberi `aria-hidden`; posisi disampaikan lewat label slide, misalnya "1 dari 3".
- Tombol panah kiri dan kanan berpindah slide saat fokus ada di dalamnya.
