Carousel

A slide gallery with prev/next, indicators, and optional autoplay. Slides are authored as item parts (index from DOM order drives slideCount); indicators are dynamic, so you provide a <template> and stimulus-zag stamps one per page.

Slide 1

Slide 2

Slide 3

<div
  data-controller="zag-carousel"
  data-part="root"
  data-zag-carousel-loop-value="true"
  class="w-full max-w-md space-y-3"
>
  <div class="relative">
    <div data-part="item-group" class="flex overflow-hidden rounded-lg">
      <div
        data-part="item"
        class="bg-primary text-primary-foreground grid h-40 min-w-full place-items-center text-2xl font-bold"
      >
        Slide 1
      </div>
      <div
        data-part="item"
        class="grid h-40 min-w-full place-items-center bg-emerald-500 text-2xl font-bold text-white"
      >
        Slide 2
      </div>
      <div
        data-part="item"
        class="grid h-40 min-w-full place-items-center bg-amber-500 text-2xl font-bold text-white"
      >
        Slide 3
      </div>
    </div>
    <div
      data-part="control"
      class="pointer-events-none absolute inset-0 flex items-center justify-between px-2"
    >
      <button
        data-part="prev-trigger"
        class="bg-popover/80 hover:bg-popover pointer-events-auto grid h-8 w-8 place-items-center rounded-full shadow"
      >
        ‹
      </button>
      <button
        data-part="next-trigger"
        class="bg-popover/80 hover:bg-popover pointer-events-auto grid h-8 w-8 place-items-center rounded-full shadow"
      >
        ›
      </button>
    </div>
  </div>
  <div
    data-part="indicator-group"
    data-zag-carousel-target="indicators"
    class="flex justify-center gap-2"
  ></div>
  <template data-zag-carousel-target="indicatorTemplate">
    <button
      data-part="indicator"
      class="bg-muted data-[current]:bg-primary h-2 w-2 rounded-full"
    ></button>
  </template>
</div>

Parts

root, control, prev-trigger, next-trigger, item-group, item, indicator-group, indicator, autoplay-trigger, progress-text.

Targets: indicators, indicatorTemplate.

Values

Attribute	Type	Default	Description
data-zag-carousel-page-value	Number	0	Initial page.
data-zag-carousel-slides-per-page-value	Number	1	Slides shown per page.
data-zag-carousel-orientation-value	String	"horizontal"	"horizontal" or "vertical".
data-zag-carousel-spacing-value	String	"0px"	Gap between slides.
data-zag-carousel-loop-value	Boolean	false	Loop past the ends.
data-zag-carousel-allow-mouse-drag-value	Boolean	false	Drag to scroll with a mouse.
data-zag-carousel-autoplay-value	Boolean	false	Auto-advance slides.

Events

Emits zag-carousel:change — detail is { page }.

Programmatic control

page (getter), next(), previous(), scrollTo(page).