huntabyte__shadcn-svelte/docs/content/components/carousel.md

title, description, component, links

title	description	component	links
Carousel	A carousel with motion and swipe built using Embla.	true	source doc api https://github.com/huntabyte/shadcn-svelte/tree/next/sites/docs/src/lib/registry/ui/carousel https://www.embla-carousel.com/docs/v8/get-started/svelte https://www.embla-carousel.com/docs/v8/api

<script> import ComponentPreview from "$lib/components/component-preview.svelte"; import ComponentSource from "$lib/components/component-source.svelte"; import PMAddComp from "$lib/components/pm-add-comp.svelte"; import PMInstall from "$lib/components/pm-install.svelte"; import Steps from "$lib/components/steps.svelte"; import Step from "$lib/components/step.svelte"; import InstallTabs from "$lib/components/install-tabs.svelte"; let { viewerData } = $props(); </script>

About

The carousel component is built using the Embla Carousel library.

Installation

{#snippet cli()} {/snippet} {#snippet manual()}

Install embla-carousel-svelte:

Copy and paste the following code into your project.

{#if viewerData} {/if} {/snippet}

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>

Examples

Sizes

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

<!-- 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 />.

<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.

<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 callback to get an instance of the carousel API.

<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 bind:api.

<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
      });
    }
  });
</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>

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>

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