About
The carousel component is built using the Embla Carousel library.
Installation
Install embla-carousel-svelte
:
Copy and paste the component source files linked at the top of this page into your project.
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 pl-[VALUE]
utility on the <Carousel.Item />
and a negative -ml-[VALUE]
on the <Carousel.Content />
.
<Carousel.Root>
<Carousel.Content class="-ml-4">
<Carousel.Item class="pl-4">...</Carousel.Item>
<Carousel.Item class="pl-4">...</Carousel.Item>
<Carousel.Item class="pl-4">...</Carousel.Item>
</Carousel.Content>
</Carousel.Root>
<Carousel.Root>
<Carousel.Content class="-ml-2 md:-ml-4">
<Carousel.Item class="pl-2 md:pl-4">...</Carousel.Item>
<Carousel.Item class="pl-2 md:pl-4">...</Carousel.Item>
<Carousel.Item class="pl-2 md:pl-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.