ICarousel ​

A row of slides you page through — screenshots, customer stories, a shelf of cards. Arrows, dots and the arrow keys.

<ICarousel :items="shots" label="Screens" v-slot="{ item }">
  <div class="grid h-40 place-items-center rounded-xl border border-border bg-muted">
    {{ item }}
  </div>
</ICarousel>

Each item is rendered through the default slot, which receives item, index and active.

Scrolling ​

The slides sit in an overflow-x-auto row with CSS scroll snapping, so touch, trackpad, shift-scroll and a dragged scrollbar move the track as well as the arrows do.

The active slide is read back from the scroll position, so swiping by hand keeps the dots in step.

More than one across ​

perView sets how many fit at the widest. Below sm it is always one.

<ICarousel :items="stories" :per-view="2" label="Customer stories" v-slot="{ item }">
  <ICard class="h-full">
    <p class="text-sm">“{{ item.quote }}”</p>
    <p class="mt-3 text-xs text-muted-foreground">{{ item.name }}</p>
  </ICard>
</ICarousel>

'auto' leaves each slide at its content's own width.

Arrows and dots ​

Both are on by default. The arrows disable at each end, and disappear when everything already fits.

There is one dot per place the track can stop at, not per slide: with several across, the last slides never reach the start of the track. The row is hidden when there is only one stop.

<ICarousel :items="shots" :dots="false" label="Screens" />

No autoplay ​

There is none. Build one from v-model:active and a timer you own; setting the model scrolls the track.

Three things come with you: a pause control, for WCAG 2.2.2; a stop under prefers-reduced-motion; and a hold while a pointer or the keyboard focus is inside.

<script setup lang="ts">
const shot = ref(0)
const playing = ref(true)
const held = ref(false)

const reduced = window.matchMedia('(prefers-reduced-motion: reduce)').matches

watchEffect((onCleanup) => {
  if (!playing.value || held.value || reduced)
    return

  const timer = setInterval(() => (shot.value = (shot.value + 1) % shots.length), 4000)
  onCleanup(() => clearInterval(timer))
})
</script>

<template>
  <div
    @pointerenter="held = true"
    @pointerleave="held = false"
    @focusin="held = true"
    @focusout="held = false"
  >
    <ICarousel v-slot="{ item }" v-model:active="shot" :items="shots" label="Screens">
      <div class="grid h-40 place-items-center rounded-xl border border-border bg-muted">
        {{ item }}
      </div>
    </ICarousel>

    <IButton variant="ghost" size="sm" @click="playing = !playing">
      <IIcon :icon="playing ? PauseIcon : PlayIcon" data-icon />
      {{ playing ? 'Pause' : 'Play' }}
    </IButton>
  </div>
</template>

Wrapping with % shots.length only works while one slide is in view. With perView above one, wrap at the last position the dots offer instead.

Styling the active slide ​

The slide in view and its dot both carry data-state="active", the rest "inactive":

<ICarousel :items="shots" :ui="{ item: 'opacity-40 data-[state=active]:opacity-100' }" />

Accessibility ​

The carousel is a group with aria-roledescription="carousel", and each slide is a group labelled "2 of 5". Give label something that names this carousel — "Customer stories", not "Carousel".

The track is focusable, and left and right move a slide at a time.

There is no live region.

Props ​

Slots ​

Models ​