Skip to content

Search documentation

Search guides, examples, and component APIs.

Quick links
↑↓ NavigateEnter OpenEsc Close
Get started

Documentation navigation

Components / Display

Carousel

A swipeable snap carousel with arrows, slide dots, and accessible autoplay.

Last changed in version 0.13.0: Add avatar groups and chips, expand the block gallery, and improve component colors, spacing, and motion.

Interactive showcase

Install

Run in your project
bunx --bun @getweini/cli@latest add carousel

Start with this example

Import the files copied by the install command, then place the component in your Vue template. The text and values in the example belong to your app; change them to fit your task.

ShowingPlan

Vue
<script setup lang="ts">
import { ref } from 'vue'
import Carousel from './components/ui/carousel/Carousel.vue'
import CarouselItem from './components/ui/carousel/CarouselItem.vue'

const index = ref(0)
const slides = ['Plan', 'Design', 'Build', 'Ship']
const messages = {
  label: 'Product stages',
  previous: 'Previous stage',
  next: 'Next stage',
  slide: (n: number, total: number) => `Stage ${n} of ${total}`,
  goTo: (n: number) => `Go to stage ${n}`,
  pause: 'Pause rotation',
  play: 'Start rotation',
  roleDescription: 'carousel',
  slideRoleDescription: 'slide',
}
</script>

<template>
  <div class="grid max-w-xl gap-2">
    <Carousel v-model="index" :messages="messages" controls-placement="outside">
      <CarouselItem v-for="slide in slides" :key="slide">
        <div
          class="flex h-48 items-center justify-center rounded-xl border border-border bg-card text-2xl font-semibold text-card-foreground"
        >
          {{ slide }}
        </div>
      </CarouselItem>
    </Carousel>
    <p class="text-sm text-muted-foreground">Showing{{ slides[index] }}</p>
  </div>
</template>

Wrap each slide in CarouselItem. Bind v-model to the current position and pass localized messages. Slides scroll and snap natively, so swiping works on touch devices.

When to use it

Featured content

Show a few highlights, such as product stages or testimonials, one at a time in limited space.

Browsing a short collection

Show several cards at once with perView and let people step through them with arrows or dots. Use overlay placement when the cards should fill the viewport.

More examples

Autoplay with loop

Rotate quotes every five seconds. A pause button is always shown, and rotation holds on hover and focus.

Autoplay with loop
<script setup lang="ts">
import { ref } from 'vue'
import Carousel from './components/ui/carousel/Carousel.vue'
import CarouselItem from './components/ui/carousel/CarouselItem.vue'

const index = ref(0)
const quotes = [
  'Setup took ten minutes.',
  'The team adopted it in a week.',
  'Support answered within the hour.',
]
const messages = {
  label: 'Customer quotes',
  previous: 'Previous quote',
  next: 'Next quote',
  slide: (n: number, total: number) => `Quote ${n} of ${total}`,
  goTo: (n: number) => `Go to quote ${n}`,
  pause: 'Pause quotes',
  play: 'Play quotes',
  roleDescription: 'carousel',
  slideRoleDescription: 'slide',
}
</script>

<template>
  <Carousel v-model="index" class="max-w-xl" :autoplay="5000" loop :messages="messages">
    <CarouselItem v-for="quote in quotes" :key="quote">
      <figure class="flex h-40 items-center justify-center rounded-xl bg-muted px-12 text-center">
        <blockquote class="text-lg font-medium text-foreground">{{ quote }}</blockquote>
      </figure>
    </CarouselItem>
  </Carousel>
</template>

Several slides at a time

Use perView to show three slides; the dots count scroll positions. Overlay controls keep the arrows and picker over the cards.

Several slides at a time
<script setup lang="ts">
import { ref } from 'vue'
import Carousel from './components/ui/carousel/Carousel.vue'
import CarouselItem from './components/ui/carousel/CarouselItem.vue'

const index = ref(0)
const products = ['Aurora', 'Beacon', 'Cinder', 'Delta', 'Ember', 'Flux']
const messages = {
  label: 'Products',
  previous: 'Previous products',
  next: 'Next products',
  slide: (n: number, total: number) => `Product ${n} of ${total}`,
  goTo: (n: number) => `Show products from ${n}`,
  pause: 'Pause',
  play: 'Play',
  roleDescription: 'carousel',
  slideRoleDescription: 'slide',
}
</script>

<template>
  <Carousel
    v-model="index"
    class="max-w-2xl"
    :per-view="3"
    controls-placement="overlay"
    :messages="messages"
  >
    <CarouselItem v-for="product in products" :key="product">
      <div
        class="flex h-40 items-start justify-center pt-4 rounded-xl border border-border bg-card font-medium text-card-foreground"
      >
        <span>{{ product }}</span>
      </div>
    </CarouselItem>
  </Carousel>
</template>

Autoplay without navigation controls

Set controls to false to hide both arrows and dots. The pause/play control stays available when autoplay is enabled.

Autoplay without navigation controls
<script setup lang="ts">
import { ref } from 'vue'
import Carousel from './components/ui/carousel/Carousel.vue'
import CarouselItem from './components/ui/carousel/CarouselItem.vue'

const index = ref(0)
const stories = ['A calmer start', 'A clearer plan', 'A stronger finish']
const messages = {
  label: 'Project stories',
  previous: 'Previous story',
  next: 'Next story',
  slide: (n: number, total: number) => `Story ${n} of ${total}`,
  goTo: (n: number) => `Go to story ${n}`,
  pause: 'Pause stories',
  play: 'Play stories',
  roleDescription: 'carousel',
  slideRoleDescription: 'slide',
}
</script>

<template>
  <Carousel
    v-model="index"
    class="max-w-xl"
    :messages="messages"
    :autoplay="5000"
    loop
    :controls="false"
  >
    <CarouselItem v-for="story in stories" :key="story">
      <article
        class="flex h-40 items-center justify-center rounded-xl border border-border bg-card p-6 text-center text-lg font-medium text-card-foreground"
      >
        {{ story }}
      </article>
    </CarouselItem>
  </Carousel>
</template>

Complete API

Every public prop, model, event, slot, and exposed member of the installed Vue parts is listed below. “Not set” means you can leave that value out; “Required” means you must provide it. Native HTML attributes also work where the component uses a native element.

Complete API for Carousel
NameType or signatureDefaultWhat it does

CarouselItem

Complete API for CarouselItem
NameType or signatureDefaultWhat it does
defaultslot(() => unknown) | undefinedOptionalContent shown inside CarouselItem.
Public type definitions
Public types
// packages/frameworks/vue/components/carousel/types.ts
// ------- TYPES -------

export interface CarouselMessages {
  /** Accessible name of the carousel region and its slide picker. */
  label: string
  previous: string
  next: string
  /** Name of one slide, for example `Slide 2 of 5`. */
  slide: (index: number, total: number) => string
  /** Name of one slide picker dot, for example `Go to slide 2`. */
  goTo: (index: number) => string
  pause: string
  play: string
  /** Localized `aria-roledescription` for the region; the attribute is omitted when absent. */
  roleDescription?: string
  /** Localized `aria-roledescription` for each slide; the attribute is omitted when absent. */
  slideRoleDescription?: string
}

export interface CarouselProps {
  /** Milliseconds between automatic advances. Off when omitted or 0. */
  autoplay?: number
  /** Slides visible at once. */
  perView?: number
  /** Wrap from the last position to the first, and the reverse. */
  loop?: boolean
  /** Show arrow and slide-picker controls. Autoplay controls remain available when enabled. */
  controls?: boolean
  /** Place navigation controls below the viewport or over the slides. */
  controlsPlacement?: 'outside' | 'overlay'
  messages: CarouselMessages
}

Implementation notes

  • The model is a position index. With perView above one, positions stop at the slide count minus perView.
  • Loop rewinds to the other end instead of cloning slides, so every slide exists once.
  • Keep CarouselItem as a direct child, or inside native elements, fragments, or v-for, so the carousel can count and name slides on the server.
  • Set --carousel-gap on the carousel to change the space between slides.

Accessibility and localization

  • Every label comes from messages, including slide and goTo functions for numbered names. Optional roleDescription and slideRoleDescription set aria-roledescription in your language.
  • Autoplay includes a pause and play button, holds while hovered or keyboard-focused, and is off under reduced motion. Live announcements are off while rotating and polite otherwise.
  • When controls are enabled, dots are a tablist with 24px targets and round 6px indicators; use arrow, Home, and End keys. Arrow keys also move slides while the viewport itself has focus.
  • The active marker follows swiping and scrolling continuously, stretching between positions. Dots lift with a soft halo on hover and squash on press; keyboard focus has the same visible affordance. Targets stay fixed.
  • Smooth scrolling and dot morphing are replaced by instant changes when the person prefers reduced motion.

Source contract and editing guidance