On This Page

About Installation Usage Sizes Spacing Orientation Options API Events Plugins

Epicenter

Local-first, open source apps

Carousel

A carousel with motion and swipe built using Embla.

Docs API Reference

Epicenter

Local-first, open source apps

Special Sponsor

<script lang="ts">
	import * as Card from "$lib/components/ui/card/index.js";
	import * as Carousel from "$lib/components/ui/carousel/index.js";
</script>
 
<Carousel.Root class="w-full max-w-[12rem] sm:max-w-xs">
	<Carousel.Content>
		{#each Array(5), i}
			<Carousel.Item>
				<div class="p-1">
					<Card.Root>
						<Card.Content class="flex aspect-square items-center justify-center p-6">
							<span class="text-4xl font-semibold">{i + 1}</span>
						</Card.Content>
					</Card.Root>
				</div>
			</Carousel.Item>
		{/each}
	</Carousel.Content>
	<Carousel.Previous />
	<Carousel.Next />
</Carousel.Root>

About

The carousel component is built using the Embla Carousel library.

Installation

pnpm dlx shadcn-svelte@latest add carousel

npx shadcn-svelte@latest add carousel

npx shadcn-svelte@latest add carousel

bun x shadcn-svelte@latest add carousel

Install `embla-carousel-svelte`:

pnpm i embla-carousel-svelte -D

npm i embla-carousel-svelte -D

yarn install embla-carousel-svelte -D

bun install embla-carousel-svelte -D

Copy and paste the following code into your project.

<script lang="ts">
  import emblaCarouselSvelte from "embla-carousel-svelte";
  import { cn, type WithElementRef } from "$lib/utils.js";
  import { getEmblaContext } from "./context.js";
  import type { HTMLAttributes } from "svelte/elements";

  let {
    ref = $bindable(null),
    class: className,
    children,
    ...restProps
  }: WithElementRef<HTMLAttributes<HTMLDivElement>> = $props();

  const emblaCtx = getEmblaContext("<Carousel.Content/>");
</script>

<div
  data-slot="carousel-content"
  class="overflow-hidden"
  use:emblaCarouselSvelte={{
    options: {
      container: "[data-embla-container]",
      slides: "[data-embla-slide]",
      ...emblaCtx.options,
      axis: emblaCtx.orientation === "horizontal" ? "x" : "y",
    },
    plugins: emblaCtx.plugins,
  }}
  onemblaInit={emblaCtx.onInit}
>
  <div
    bind:this={ref}
    class={cn(
      "flex",
      emblaCtx.orientation === "horizontal" ? "-ms-4" : "-mt-4 flex-col",
      className
    )}
    data-embla-container=""
    {...restProps}
  >
    {@render children?.()}
  </div>
</div>

Usage

<script lang="ts">
  import * as Carousel from "$lib/components/ui/carousel/index.js";
</script>

<Carousel.Root>
  <Carousel.Content>
    <Carousel.Item>...</Carousel.Item>
    <Carousel.Item>...</Carousel.Item>
    <Carousel.Item>...</Carousel.Item>
  </Carousel.Content>
  <Carousel.Previous />
  <Carousel.Next />
</Carousel.Root>

Sizes

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

<script lang="ts">
	import * as Card from "$lib/components/ui/card/index.js";
	import * as Carousel from "$lib/components/ui/carousel/index.js";
</script>
 
<Carousel.Root
	opts={{
		align: "start",
	}}
	class="w-full max-w-[12rem] sm:max-w-xs md:max-w-sm"
>
	<Carousel.Content>
		{#each Array(5) as _, i (i)}
			<Carousel.Item class="basis-1/2 lg:basis-1/3">
				<div class="p-1">
					<Card.Root>
						<Card.Content class="flex aspect-square items-center justify-center p-6">
							<span class="text-3xl font-semibold">{i + 1}</span>
						</Card.Content>
					</Card.Root>
				</div>
			</Carousel.Item>
		{/each}
	</Carousel.Content>
	<Carousel.Previous />
	<Carousel.Next />
</Carousel.Root>

<!-- 33% of the carousel width. -->
<Carousel.Root>
  <Carousel.Content>
    <Carousel.Item class="basis-1/3">...</Carousel.Item>
    <Carousel.Item class="basis-1/3">...</Carousel.Item>
    <Carousel.Item class="basis-1/3">...</Carousel.Item>
  </Carousel.Content>
</Carousel.Root>

<!-- 50% on small screens and 33% on larger screens. -->
<Carousel.Root>
  <Carousel.Content>
    <Carousel.Item class="md:basis-1/2 lg:basis-1/3">...</Carousel.Item>
    <Carousel.Item class="md:basis-1/2 lg:basis-1/3">...</Carousel.Item>
    <Carousel.Item class="md:basis-1/2 lg:basis-1/3">...</Carousel.Item>
  </Carousel.Content>
</Carousel.Root>

Spacing

To set the spacing between the items, we use a ps-[VALUE] utility on the <Carousel.Item /> and a negative -ms-[VALUE] on the <Carousel.Content />.

<script lang="ts">
	import * as Card from "$lib/components/ui/card/index.js";
	import * as Carousel from "$lib/components/ui/carousel/index.js";
</script>
 
<Carousel.Root class="w-full max-w-[12rem] sm:max-w-xs md:max-w-sm">
	<Carousel.Content class="-ms-1">
		{#each Array(5) as _, i (i)}
			<Carousel.Item class="basis-1/2 ps-1 lg:basis-1/3">
				<div class="p-1">
					<Card.Root>
						<Card.Content class="flex aspect-square items-center justify-center p-6">
							<span class="text-2xl font-semibold">{i + 1}</span>
						</Card.Content>
					</Card.Root>
				</div>
			</Carousel.Item>
		{/each}
	</Carousel.Content>
	<Carousel.Previous />
	<Carousel.Next />
</Carousel.Root>

<Carousel.Root>
  <Carousel.Content class="-ms-4">
    <Carousel.Item class="ps-4">...</Carousel.Item>
    <Carousel.Item class="ps-4">...</Carousel.Item>
    <Carousel.Item class="ps-4">...</Carousel.Item>
  </Carousel.Content>
</Carousel.Root>

<Carousel.Root>
  <Carousel.Content class="-ms-2 md:-ms-4">
    <Carousel.Item class="ps-2 md:ps-4">...</Carousel.Item>
    <Carousel.Item class="ps-2 md:ps-4">...</Carousel.Item>
    <Carousel.Item class="ps-2 md:ps-4">...</Carousel.Item>
  </Carousel.Content>
</Carousel.Root>

Orientation

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

<script lang="ts">
	import * as Card from "$lib/components/ui/card/index.js";
	import * as Carousel from "$lib/components/ui/carousel/index.js";
</script>
 
<Carousel.Root
	opts={{
		align: "start",
	}}
	orientation="vertical"
	class="w-full max-w-xs"
>
	<Carousel.Content class="-mt-1 h-[270px]">
		{#each Array(5) as _, i (i)}
			<Carousel.Item class="basis-1/2 pt-1">
				<div class="p-1">
					<Card.Root>
						<Card.Content class="flex items-center justify-center p-6">
							<span class="text-3xl font-semibold">{i + 1}</span>
						</Card.Content>
					</Card.Root>
				</div>
			</Carousel.Item>
		{/each}
	</Carousel.Content>
	<Carousel.Previous />
	<Carousel.Next />
</Carousel.Root>

<Carousel.Root orientation="vertical | horizontal">
  <Carousel.Content>
    <Carousel.Item>...</Carousel.Item>
    <Carousel.Item>...</Carousel.Item>
    <Carousel.Item>...</Carousel.Item>
  </Carousel.Content>
</Carousel.Root>

Options

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

<Carousel.Root
  opts={{
    align: "start",
    loop: true,
  }}
>
  <Carousel.Content>
    <Carousel.Item>...</Carousel.Item>
    <Carousel.Item>...</Carousel.Item>
    <Carousel.Item>...</Carousel.Item>
  </Carousel.Content>
</Carousel.Root>

API

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

Slide 0 of 0

<script lang="ts">
	import * as Card from "$lib/components/ui/card/index.js";
	import * as Carousel from "$lib/components/ui/carousel/index.js";
	import type { CarouselAPI } from "$lib/components/ui/carousel/context.js";
 
	let api = $state<CarouselAPI>();
 
	const count = $derived(api ? api.scrollSnapList().length : 0);
	let current = $state(0);
 
	$effect(() => {
		if (api) {
			current = api.selectedScrollSnap() + 1;
			api.on("select", () => {
				current = api!.selectedScrollSnap() + 1;
			});
		}
	});
</script>
 
<div class="mx-auto max-w-[10rem] sm:max-w-xs">
	<Carousel.Root setApi={(emblaApi) => (api = emblaApi)} class="w-full max-w-xs">
		<Carousel.Content>
			{#each Array(5) as _, i (i)}
				<Carousel.Item>
					<Card.Root class="m-px">
						<Card.Content class="flex aspect-square items-center justify-center p-6">
							<span class="text-4xl font-semibold">{i + 1}</span>
						</Card.Content>
					</Card.Root>
				</Carousel.Item>
			{/each}
		</Carousel.Content>
		<Carousel.Previous />
		<Carousel.Next />
	</Carousel.Root>
	<div class="py-2 text-center text-sm text-muted-foreground">
		Slide {current} of {count}
	</div>
</div>

<script lang="ts">
  import { type CarouselAPI } from "$lib/components/ui/carousel/context.js";
  import * as Carousel from "$lib/components/ui/carousel/index.js";
 
  let api = $state<CarouselAPI>();
  let current = $state(0);
  const count = $derived(api ? api.scrollSnapList().length : 0);
 
  $effect(() => {
    if (api) {
      current = api.selectedScrollSnap() + 1;
      api.on("select", () => {
        current = api!.selectedScrollSnap() + 1;
      });
    }
  });
</script>
 
<Carousel.Root setApi={(emblaApi) => (api = emblaApi)}>
  <Carousel.Content>
    <Carousel.Item>...</Carousel.Item>
    <Carousel.Item>...</Carousel.Item>
    <Carousel.Item>...</Carousel.Item>
  </Carousel.Content>
</Carousel.Root>

Events

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

<script lang="ts">
  import { type CarouselAPI } from "$lib/components/ui/carousel/context.js";
  import * as Carousel from "$lib/components/ui/carousel/index.js";
 
  let api = $state<CarouselAPI>();
 
  $effect(() => {
    if (api) {
      api.on("select", () => {
        // Do something on select.
      });
    }
  });
</script>
 
<Carousel.Root setApi={(emblaApi) => (api = emblaApi)}>
  <Carousel.Content>
    <Carousel.Item>...</Carousel.Item>
    <Carousel.Item>...</Carousel.Item>
    <Carousel.Item>...</Carousel.Item>
  </Carousel.Content>
</Carousel.Root>

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

Plugins

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

<script lang="ts">
  import Autoplay from "embla-carousel-autoplay";
  import * as Carousel from "$lib/components/ui/carousel/index.js";
</script>
 
<Carousel.Root
  plugins={[
    Autoplay({
      delay: 2000,
    }),
  ]}
>
  <!-- ... -->
</Carousel.Root>

<script lang="ts">
	import Autoplay from "embla-carousel-autoplay";
	import * as Card from "$lib/components/ui/card/index.js";
	import * as Carousel from "$lib/components/ui/carousel/index.js";
 
	const plugin = Autoplay({ delay: 2000, stopOnInteraction: true });
</script>
 
<Carousel.Root
	plugins={[plugin]}
	class="w-full max-w-[10rem] sm:max-w-xs"
	onmouseenter={plugin.stop}
	onmouseleave={plugin.reset}
>
	<Carousel.Content>
		{#each Array(5) as _, i (i)}
			<Carousel.Item>
				<div class="p-1">
					<Card.Root>
						<Card.Content class="flex aspect-square items-center justify-center p-6">
							<span class="text-4xl font-semibold">{i + 1}</span>
						</Card.Content>
					</Card.Root>
				</div>
			</Carousel.Item>
		{/each}
	</Carousel.Content>
	<Carousel.Previous />
	<Carousel.Next />
</Carousel.Root>

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

Card Chart

Epicenter

Carousel

Epicenter

Install embla-carousel-svelte:

Copy and paste the following code into your project.

Install `embla-carousel-svelte`: