Carousel

A carousel with motion and swipe built using Embla.

1
import { Card, CardContent } from "@/components/ui/pxl/card";
2
import {
3
  Carousel,
4
  CarouselContent,
5
  CarouselItem,
6
  CarouselNext,
7
  CarouselPrevious,
8
} from "@/components/ui/pxl/carousel";
9

10
const slides = [1, 2, 3, 4, 5];
11

12
export default function CarouselDemo() {
13
  return (
14
    <Carousel className="w-full max-w-40">
15
      <CarouselContent>
16
        {slides.map((slide) => (
17
          <CarouselItem key={slide}>
18
            <Card>
19
              <CardContent className="flex aspect-square items-center justify-center p-3">
20
                <span className="font-medium text-2xl">{slide}</span>
21
              </CardContent>
22
            </Card>
23
          </CarouselItem>
24
        ))}
25
      </CarouselContent>
26
      <CarouselPrevious />
27
      <CarouselNext />
28
    </Carousel>
29
  );
30
}

About

The carousel component is built using the Embla Carousel library.

Installation

Command
Manual

pnpm dlx shadcn@latest add pxl-ui/registry/carousel

Install the following dependencies:

pnpm add embla-carousel-react

Copy and paste the following code into your project.

1
"use client";
2

3
import useEmblaCarousel, {
4
  type UseEmblaCarouselType,
5
} from "embla-carousel-react";
6
import {
7
  type ComponentProps,
8
  createContext,
9
  type KeyboardEvent,
10
  useCallback,
11
  useContext,
12
  useEffect,
13
  useState,
14
} from "react";
15

16
import { cn } from "@/lib/utils";
17
import { Button } from "@/ui/pxl/button";
18

19
type CarouselApi = UseEmblaCarouselType[1];
20
type UseCarouselParameters = Parameters<typeof useEmblaCarousel>;
21
type CarouselOptions = UseCarouselParameters[0];
22
type CarouselPlugin = UseCarouselParameters[1];
23

24
type CarouselProps = {
25
  opts?: CarouselOptions;
26
  plugins?: CarouselPlugin;
27
  orientation?: "horizontal" | "vertical";
28
  setApi?: (api: CarouselApi) => void;
29
};
30

31
type CarouselContextProps = {
32
  carouselRef: ReturnType<typeof useEmblaCarousel>[0];
33
  api: ReturnType<typeof useEmblaCarousel>[1];
34
  scrollPrev: () => void;
35
  scrollNext: () => void;
36
  canScrollPrev: boolean;
37
  canScrollNext: boolean;
38
} & CarouselProps;
39

40
const CarouselContext = createContext<CarouselContextProps | null>(null);
41

42
function useCarousel() {
43
  const context = useContext(CarouselContext);
44

45
  if (!context) {
46
    throw new Error("useCarousel must be used within a <Carousel />");
47
  }
48

49
  return context;
50
}
51

52
function Carousel({
53
  orientation = "horizontal",
54
  opts,
55
  setApi,
56
  plugins,
57
  className,
58
  children,
59
  ...props
60
}: ComponentProps<"div"> & CarouselProps) {
61
  const [carouselRef, api] = useEmblaCarousel(
62
    {
63
      ...opts,
64
      axis: orientation === "horizontal" ? "x" : "y",
65
    },
66
    plugins,
67
  );
68
  const [canScrollPrev, setCanScrollPrev] = useState(false);
69
  const [canScrollNext, setCanScrollNext] = useState(false);
70

71
  const onSelect = useCallback((api: CarouselApi) => {
72
    if (!api) return;
73
    setCanScrollPrev(api.canScrollPrev());
74
    setCanScrollNext(api.canScrollNext());
75
  }, []);
76

77
  const scrollPrev = useCallback(() => {
78
    api?.scrollPrev();
79
  }, [api]);
80

81
  const scrollNext = useCallback(() => {
82
    api?.scrollNext();
83
  }, [api]);
84

85
  const handleKeyDown = useCallback(
86
    (event: KeyboardEvent<HTMLDivElement>) => {
87
      if (event.key === "ArrowLeft") {
88
        event.preventDefault();
89
        scrollPrev();
90
      } else if (event.key === "ArrowRight") {
91
        event.preventDefault();
92
        scrollNext();
93
      }
94
    },
95
    [scrollPrev, scrollNext],
96
  );
97

98
  useEffect(() => {
99
    if (!api || !setApi) return;
100
    setApi(api);
101
  }, [api, setApi]);
102

103
  useEffect(() => {
104
    if (!api) return;
105
    onSelect(api);
106
    api.on("reInit", onSelect);
107
    api.on("select", onSelect);
108

109
    return () => {
110
      api?.off("select", onSelect);
111
    };
112
  }, [api, onSelect]);
113

114
  return (
115
    <CarouselContext.Provider
116
      value={{
117
        carouselRef,
118
        api: api,
119
        opts,
120
        orientation:
121
          orientation || (opts?.axis === "y" ? "vertical" : "horizontal"),
122
        scrollPrev,
123
        scrollNext,
124
        canScrollPrev,
125
        canScrollNext,
126
      }}
127
    >
128
      {/** biome-ignore lint/a11y/useSemanticElements: carousel */}
129
      <div
130
        onKeyDownCapture={handleKeyDown}
131
        className={cn("relative", className)}
132
        role="region"
133
        aria-roledescription="carousel"
134
        data-slot="carousel"
135
        {...props}
136
      >
137
        {children}
138
      </div>
139
    </CarouselContext.Provider>
140
  );
141
}
142

143
function CarouselContent({ className, ...props }: ComponentProps<"div">) {
144
  const { carouselRef, orientation } = useCarousel();
145

146
  return (
147
    <div
148
      ref={carouselRef}
149
      className="overflow-hidden"
150
      data-slot="carousel-content"
151
    >
152
      <div
153
        className={cn(
154
          "flex",
155
          orientation === "horizontal" ? "-ml-4" : "-mt-4 flex-col",
156
          className,
157
        )}
158
        {...props}
159
      />
160
    </div>
161
  );
162
}
163

164
function CarouselItem({ className, ...props }: ComponentProps<"div">) {
165
  const { orientation } = useCarousel();
166

167
  return (
168
    // biome-ignore lint/a11y/useSemanticElements: carousel
169
    <div
170
      role="group"
171
      aria-roledescription="slide"
172
      data-slot="carousel-item"
173
      className={cn(
174
        "min-w-0 shrink-0 grow-0 basis-full",
175
        orientation === "horizontal" ? "pl-4" : "pt-4",
176
        className,
177
      )}
178
      {...props}
179
    />
180
  );
181
}
182

183
function CarouselPrevious({
184
  className,
185
  variant = "outline",
186
  size = "icon-sm",
187
  ...props
188
}: ComponentProps<typeof Button>) {
189
  const { orientation, scrollPrev, canScrollPrev } = useCarousel();
190

191
  return (
192
    <Button
193
      data-slot="carousel-previous"
194
      variant={variant}
195
      size={size}
196
      className={cn(
197
        "absolute touch-manipulation",
198
        orientation === "horizontal"
199
          ? "inset-y-0 -left-12 my-auto"
200
          : "-top-12 left-1/2 -translate-x-1/2 rotate-90",
201
        className,
202
      )}
203
      disabled={!canScrollPrev}
204
      onClick={scrollPrev}
205
      {...props}
206
    >
207
      <svg
208
        xmlns="http://www.w3.org/2000/svg"
209
        fill="currentColor"
210
        viewBox="0 0 24 24"
211
      >
212
        <path d="M8 13v-2h2v2H8Zm2-2V9h2v2h-2Zm0 4v-2h2v2h-2Zm2-6V7h2v2h-2Zm0 8v-2h2v2h-2Zm2-10V5h2v2h-2Zm0 12v-2h2v2h-2Z" />
213
      </svg>
214
      <span className="sr-only">Previous slide</span>
215
    </Button>
216
  );
217
}
218

219
function CarouselNext({
220
  className,
221
  variant = "outline",
222
  size = "icon-sm",
223
  ...props
224
}: ComponentProps<typeof Button>) {
225
  const { orientation, scrollNext, canScrollNext } = useCarousel();
226

227
  return (
228
    <Button
229
      data-slot="carousel-next"
230
      variant={variant}
231
      size={size}
232
      className={cn(
233
        "absolute touch-manipulation",
234
        orientation === "horizontal"
235
          ? "inset-y-0 -right-12 my-auto"
236
          : "-bottom-12 left-1/2 -translate-x-1/2 rotate-90",
237
        className,
238
      )}
239
      disabled={!canScrollNext}
240
      onClick={scrollNext}
241
      {...props}
242
    >
243
      <svg
244
        xmlns="http://www.w3.org/2000/svg"
245
        fill="currentColor"
246
        viewBox="0 0 24 24"
247
      >
248
        <path d="M16 13v-2h-2v2h2Zm-2-2V9h-2v2h2Zm0 4v-2h-2v2h2Zm-2-6V7h-2v2h2Zm0 8v-2h-2v2h2ZM10 7V5H8v2h2Zm0 12v-2H8v2h2Z" />
249
      </svg>
250
      <span className="sr-only">Next slide</span>
251
    </Button>
252
  );
253
}
254

255
export {
256
  Carousel,
257
  type CarouselApi,
258
  CarouselContent,
259
  CarouselItem,
260
  CarouselNext,
261
  CarouselPrevious,
262
  useCarousel,
263
};

Update the import paths to match your project setup.

Usage

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

<Carousel>
  <CarouselContent>
    <CarouselItem>...</CarouselItem>
    <CarouselItem>...</CarouselItem>
    <CarouselItem>...</CarouselItem>
  </CarouselContent>
  <CarouselPrevious />
  <CarouselNext />
</Carousel>

Composition

Use the following composition to build a Carousel:

Carousel
├── CarouselContent
│   ├── CarouselItem
│   └── CarouselItem
├── CarouselPrevious
└── CarouselNext

Sizes

To set the size of the items, you can use the basis utility class on the <CarouselItem />.

1
// 33% of the carousel width.
2
<Carousel>
3
  <CarouselContent>
4
    <CarouselItem className="basis-1/3">...</CarouselItem>
5
    <CarouselItem className="basis-1/3">...</CarouselItem>
6
    <CarouselItem className="basis-1/3">...</CarouselItem>
7
  </CarouselContent>
8
</Carousel>

1
// 50% on small screens and 33% on larger screens.
2
<Carousel>
3
  <CarouselContent>
4
    <CarouselItem className="md:basis-1/2 lg:basis-1/3">...</CarouselItem>
5
    <CarouselItem className="md:basis-1/2 lg:basis-1/3">...</CarouselItem>
6
    <CarouselItem className="md:basis-1/2 lg:basis-1/3">...</CarouselItem>
7
  </CarouselContent>
8
</Carousel>

Spacing

To set the spacing between the items, we use a pl-[VALUE] utility on the <CarouselItem /> and a negative -ml-[VALUE] on the <CarouselContent />.

1
<Carousel>
2
  <CarouselContent className="-ml-4">
3
    <CarouselItem className="pl-4">...</CarouselItem>
4
    <CarouselItem className="pl-4">...</CarouselItem>
5
    <CarouselItem className="pl-4">...</CarouselItem>
6
  </CarouselContent>
7
</Carousel>

1
<Carousel>
2
  <CarouselContent className="-ml-2 md:-ml-4">
3
    <CarouselItem className="pl-2 md:pl-4">...</CarouselItem>
4
    <CarouselItem className="pl-2 md:pl-4">...</CarouselItem>
5
    <CarouselItem className="pl-2 md:pl-4">...</CarouselItem>
6
  </CarouselContent>
7
</Carousel>

Orientation

Use the orientation prop to set the orientation of the carousel.

1
<Carousel orientation="vertical | horizontal">
2
  <CarouselContent>
3
    <CarouselItem>...</CarouselItem>
4
    <CarouselItem>...</CarouselItem>
5
    <CarouselItem>...</CarouselItem>
6
  </CarouselContent>
7
</Carousel>

Options

You can pass options to the carousel using the opts prop. See the Embla Carousel docs for more information.

1
<Carousel
2
  opts={{
3
    align: "start",
4
    loop: true,
5
  }}
6
>
7
  <CarouselContent>
8
    <CarouselItem>...</CarouselItem>
9
    <CarouselItem>...</CarouselItem>
10
    <CarouselItem>...</CarouselItem>
11
  </CarouselContent>
12
</Carousel>

API

Use a state and the setApi prop to get an instance of the carousel API.

1
import { type CarouselApi } from "@/components/ui/pxl/carousel"
2

3
export function Example() {
4
  const [api, setApi] = useState<CarouselApi>()
5
  const [current, setCurrent] = useState(0)
6
  const [count, setCount] = useState(0)
7

8
  useEffect(() => {
9
    if (!api) {
10
      return
11
    }
12

13
    setCount(api.scrollSnapList().length)
14
    setCurrent(api.selectedScrollSnap() + 1)
15

16
    api.on("select", () => {
17
      setCurrent(api.selectedScrollSnap() + 1)
18
    })
19
  }, [api])
20

21
  return (
22
    <Carousel setApi={setApi}>
23
      <CarouselContent>
24
        <CarouselItem>...</CarouselItem>
25
        <CarouselItem>...</CarouselItem>
26
        <CarouselItem>...</CarouselItem>
27
      </CarouselContent>
28
    </Carousel>
29
  )
30
}

Events

You can listen to events using the api instance from setApi.

1
import { type CarouselApi } from "@/components/ui/pxl/carousel"
2

3
export function Example() {
4
  const [api, setApi] = useState<CarouselApi>()
5

6
  useEffect(() => {
7
    if (!api) {
8
      return
9
    }
10

11
    api.on("select", () => {
12
      // Do something on select.
13
    })
14
  }, [api])
15

16
  return (
17
    <Carousel setApi={setApi}>
18
      <CarouselContent>
19
        <CarouselItem>...</CarouselItem>
20
        <CarouselItem>...</CarouselItem>
21
        <CarouselItem>...</CarouselItem>
22
      </CarouselContent>
23
    </Carousel>
24
  )
25
}

See the Embla Carousel docs for more information on using events.

Plugins

You can use the plugins prop to add plugins to the carousel.

1
import Autoplay from "embla-carousel-autoplay"
2

3
export function Example() {
4
  return (
5
    <Carousel
6
      plugins={[
7
        Autoplay({
8
          delay: 2000,
9
        }),
10
      ]}
11
    >
12
      // ...
13
    </Carousel>
14
  )
15
}

RTL

To enable RTL support in shadcn/ui, see the RTL configuration guide.

When localizing the carousel for RTL languages, you need to set the direction option in the opts prop to match the text direction. This ensures the carousel scrolls in the correct direction.

1
<Carousel
2
  dir={dir}
3
  opts={{
4
    direction: dir,
5
  }}
6
>
7
  <CarouselContent>
8
    <CarouselItem>...</CarouselItem>
9
    <CarouselItem>...</CarouselItem>
10
    <CarouselItem>...</CarouselItem>
11
  </CarouselContent>
12
  <CarouselPrevious className="rtl:rotate-180" />
13
  <CarouselNext className="rtl:rotate-180" />
14
</Carousel>

The direction option accepts "ltr" or "rtl" and should match the dir prop value. You may also want to rotate the navigation buttons using the rtl:rotate-180 class to ensure they point in the correct direction.

API Reference

See the Embla Carousel docs for more information on props and plugins.