Carousel
A lightweight carousel component with CSS transitions and drag support. No additional animation library required.
Installation
pnpm dlx shadcn@latest add https://carouselcn.vercel.app/r/carousel.jsonIf you are using a namespaced registry, you can use the following command:
pnpm dlx shadcn@latest add @carouselcn/carouselUsage
import {
Carousel,
CarouselContent,
CarouselItem,
CarouselNavigation,
CarouselIndicator,
} from "@/components/ui/carousel";<Carousel>
<CarouselContent>
<CarouselItem>Slide 1</CarouselItem>
<CarouselItem>Slide 2</CarouselItem>
<CarouselItem>Slide 3</CarouselItem>
</CarouselContent>
<CarouselNavigation />
<CarouselIndicator />
</Carousel>Examples
Basic
Custom Indicator
Use controlled state with index and onIndexChange to build custom indicators.
Loop
Enable looping with the loop prop. When reaching the last slide, navigating forward jumps back to the first slide.
Vertical
Use orientation="vertical" for vertical sliding. The container must have an explicit height.
Sizes and Spacing
Use -ml-4 on CarouselContent and pl-4 on CarouselItem to add spacing between items. Use basis-1/3 (or other values) to show multiple items at once.
Navigation Position
Use className on CarouselNavigation to reposition the navigation buttons anywhere you want.
Custom Navigation
Use the useCarousel hook to build completely custom navigation elements.
Autoplay
Use the useCarouselAutoplay hook to automatically advance slides. The hook provides play, pause, and toggle controls.
API Reference
Carousel
The root component that provides context for the carousel.
Prop
Type
CarouselContent
Container for carousel items with drag and transition support.
Prop
Type
CarouselItem
Individual slide wrapper.
Prop
Type
CarouselNavigation
Previous/next navigation buttons.
Prop
Type
CarouselIndicator
Dot indicators showing current slide position.
Prop
Type
useCarousel
Hook to access carousel state and controls.
const { index, setIndex, itemsCount } = useCarousel();useCarouselAutoplay
Hook to enable automatic slide advancement.
const { isPlaying, play, pause, toggle } = useCarouselAutoplay({
interval: 3000,
autoStart: true,
});Prop
Type
Returns:
Prop
Type
Comparison with Carousel Motion
This component uses CSS transitions instead of Motion (Framer Motion). Choose this version if:
- You want a smaller bundle size
- You don't need spring-based animations
- You're not already using Motion in your project
For smoother, spring-based animations, consider using Carousel Motion.