Carousel

A carousel with motion and swipe built using Embla.

Component Source Primitive API Reference

Preview ​

1
2
3
4
5
6
7
8
9
10
1
2
3
4
5
6
7
8
9
10

Dependencies ​

Installation ​

bash
npx sigma-ui add carousel

Examples ​

More examples at: Embla Carousel docs

Basic ​

1
2
3
4
5

Sizes ​

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

1
2
3
4
5

Example

vue
// 33% of the carousel width.
<Carousel>
  <CarouselContent>
    <CarouselItem class="basis-1/3">...</CarouselItem>
    <CarouselItem class="basis-1/3">...</CarouselItem>
    <CarouselItem class="basis-1/3">...</CarouselItem>
  </CarouselContent>
</Carousel>

Responsive

vue
// 50% on small screens and 33% on larger screens.
<Carousel>
  <CarouselContent>
    <CarouselItem class="md:basis-1/2 lg:basis-1/3">...</CarouselItem>
    <CarouselItem class="md:basis-1/2 lg:basis-1/3">...</CarouselItem>
    <CarouselItem class="md:basis-1/2 lg:basis-1/3">...</CarouselItem>
  </CarouselContent>
</Carousel>

Spacing ​

In this component, the easiest way to set the spacing between items is to use a positive padding on the <CarouselItem /> and a negative margin on the <CarouselContent />.

1
2
3
4
5

Example

vue
<template>
  <Carousel>
    <CarouselContent class="-ml-4">
      <CarouselItem class="pl-4">
        ...
      </CarouselItem>
      <CarouselItem class="pl-4">
        ...
      </CarouselItem>
      <CarouselItem class="pl-4">
        ...
      </CarouselItem>
    </CarouselContent>
  </Carousel>
</template>

Responsive

vue
<template>
  <Carousel>
    <CarouselContent class="-ml-2 md:-ml-4">
      <CarouselItem class="pl-2 md:pl-4">
        ...
      </CarouselItem>
      <CarouselItem class="pl-2 md:pl-4">
        ...
      </CarouselItem>
      <CarouselItem class="pl-2 md:pl-4">
        ...
      </CarouselItem>
    </CarouselContent>
  </Carousel>
</template>

Orientation ​

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

1
2
3
4
5
vue
<Carousel orientation="vertical | horizontal">
  ...
</Carousel>

Thumbnails ​

1
2
3
4
5
6
7
8
9
10
1
2
3
4
5
6
7
8
9
10

Options ​

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

vue
<template>
  <Carousel
    :opts="{
      align: 'start',
      loop: true,
    }"
  >
    <CarouselContent>
      <CarouselItem>...</CarouselItem>
      <CarouselItem>...</CarouselItem>
      <CarouselItem>...</CarouselItem>
    </CarouselContent>
  </Carousel>
</template>

API ​

Method 1 ​

Use the @init-api emit method on <Carousel /> component to set the instance of the API.

1
2
3
4
5
Slide 0 of 0

Method 2 ​

You can access it through setting a template ref on the <Carousel /> component.

vue
<script setup>
const carouselContainerRef = ref<InstanceType<typeof Carousel> | null>(null)

function accessApi() {
  carouselContainerRef.value?.carouselApi.on('select', () => {})
}
</script>

<template>
  <Carousel ref="carouselContainerRef">
    ...
  </Carousel>
</template>

Events ​

You can listen to events using the API. To get the API instance use the @init-api emit method on the <Carousel /> component

vue
<script setup>
import { nextTick, ref, watch } from 'vue'
import { useCarousel } from '@/components/ui/carousel'

const api = ref<CarouselApi>()

function setApi(val: CarouselApi) {
  api.value = val
}

const stop = watch(api, (api) => {
  if (!api) {
    return
    }

  // Watch only once
  nextTick(() => stop())

  api.on('select', () => {
    // Do something on select
  })
})
</script>

<template>
  <Carousel @init-api="setApi">
    ...
  </Carousel>
</template>

More about events: Embla Carousel docs | Events

Slot Props ​

You can get the reactive slot props like carouselRef, canScrollNext..Prev, scrollNext..Prev using the v-slot directive in the <Carousel v-slot="slotProps" /> component to extend the functionality.

vue
<template>
  <Carousel v-slot="{ canScrollNext, canScrollPrev }">
    ...
    <CarouselPrevious v-if="canScrollPrev" />
    <CarouselNext v-if="canScrollNext" />
  </Carousel>
</template>

Plugins ​

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

bash
npm i embla-carousel-autoplay
vue
<script setup lang="ts">
import Autoplay from 'embla-carousel-autoplay'
</script>

<template>
  <Carousel
    class="w-full max-w-xs"
    :plugins="[Autoplay({
      delay: 2000,
    })]"
  >
    ...
  </Carousel>
</template>
1
2
3
4
5

More about plugins: Embla Carousel docs | Plugins

Edit this page on GitHub