Carousel

A carousel component allows users to scroll through a collection of items, such as images, cards, or testimonials, in a space-efficient manner. Built on top of Embla Carousel, it provides a smooth, accessible, and highly customizable experience.

Installation

Install the component using the Tailgrids CLI.

npx @tailgrids/cli add carousel

Anatomy

Import the components and wrap your items.

import {
  Carousel,
  CarouselContent,
  CarouselItem,
  CarouselNext,
  CarouselPrevious
} from "@/components/carousel";

export const CarouselExample = () => (
  <Carousel>
    <CarouselContent>
      <CarouselItem>...</CarouselItem>
      <CarouselItem>...</CarouselItem>
      <CarouselItem>...</CarouselItem>
    </CarouselContent>
    <CarouselPrevious />
    <CarouselNext />
  </Carousel>
);

Examples

Default Carousel

Testimonials

A single-item carousel for customer reviews and feedback.

“This carousel component is incredibly smooth. I love how easy it was to integrate with our design system.”

Jane Doe

Lead Designer at TechCo

“Vertical orientation was exactly what we needed for our sidebar news feed. Performance is top-notch.”

John Smith

Frontend Engineer at StartupX

“The API accessibility is fantastic. We were able to build complex custom navigation in minutes.”

Sarah Brown

Product Manager at WebDev

Vertical Orientation

Set the orientation="vertical" prop to create a vertical scrolling carousel.

Slide 1

Slide 2

Slide 3

Slide 4

Slide 5

API Control & Events

Use the setApi prop to get access to the Embla Carousel instance for custom controls or events.

Slide 0 of 0

Plugin & Options

Use the opts prop to pass configuration options to the carousel and plugins prop to add plugins.

API Reference

Carousel

The root component that provides context and manages the Embla instance.

Prop	Type	Default	Description
`opts`	`CarouselOptions`	-	Options for the Embla Carousel instance.
`plugins`	`CarouselPlugin[]`	-	Plugins for the Embla Carousel instance.
`orientation`	`'horizontal' \| 'vertical'`	`'horizontal'`	The orientation of the carousel.
`setApi`	`(api: CarouselApi) => void`	-	Callback to receive the Embla Carousel API.
`className`	`string`	-	Additional CSS classes for the root container.

CarouselContent

The wrapper for the carousel items.

Prop	Type	Description
`className`	`string`	Additional CSS classes for the slides wrapper.
`children`	`React.ReactNode`	The `CarouselItem` components.

CarouselItem

A single slide within the carousel.

Prop	Type	Description
`className`	`string`	Additional CSS classes for the slide.
`children`	`React.ReactNode`	The content of the slide.

CarouselPrevious / CarouselNext

Navigation buttons for the carousel. They accept all props of the Button component.

Prop	Type	Default	Description
`variant`	`'primary' \| 'danger' \| 'success' \| 'ghost'`	`'ghost'`	The visual variant of the button.
`appearance`	`'outline' \| 'fill'`	`'outline'`	The visual appearance of the button.
`size`	`'xs' \| 'sm' \| 'md' \| 'lg'`	`'sm'`	The size of the navigation button.
`className`	`string`	-	Additional CSS classes for the button.

See the Embla Cacrousel Guides for more information.

Accessibility

Use the Embla Carousel Accessibility plugin for best accessibility support.
Built with keyboard navigation support (Arrow keys automatically scroll items).
Uses role="region" with aria-roledescription="carousel" for the outer container.
Each slide has role="group" and aria-roledescription="slide".
Buttons include sr-only text for screen readers ("Previous slide", "Next slide").
Properly handles disabled states when the carousel cannot scroll further.

Carousel

CLI

Manual

On this page