Carousel
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
Section titled “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.
Senja di Kota
Rara Senandika
Kaset Pertama
Bima Laras
Pulang Sore
Nada Kirana
Hujan Bulan Juni
Arka Wening
Lampu Kota
Sinta Maharani
Senja di Kota
Rara Senandika
Kaset Pertama
Bima Laras
Pulang Sore
Nada Kirana
Hujan Bulan Juni
Arka Wening
Lampu Kota
Sinta Maharani
Anatomy
Section titled “Anatomy”- 1Current slide
- 2Next slide, partly shown
- 3Position 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 areinput. - 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.
| 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. |
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> )}<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>// 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
Section titled “Install”npx shadcn@latest add https://design.sosialoka.tech/r/react/carousel.jsonnpx shadcn-vue@latest add https://design.sosialoka.tech/r/vue/carousel.jsonAccessibility
Section titled “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.
