Carousel `<mv-carousel>`

Karussell auf Basis von nativem Scroll Snap: Pfeile, per IntersectionObserver synchronisierte Punkte, Tastatur, Endlosschleife, Autoplay mit Fortschrittspunkt (pausiert bei Hover, Fokus und reduzierter Bewegung), mehrere Slides pro Ansicht, vertikaler Modus und Ziehen mit der Maus.

Kategorie	Layout
Typ	Web Component (`<mv-carousel>`)
Status	stabil
Keywords	carousel, slider, scroll-snap, autoplay, gallery, swipe, drag

When to use

A set of slides, like featured articles or photos, must be browsed one or a few at a time with arrows and dots
A horizontally scrollable row of cards should snap into place and support swipe, drag and keyboard
A hero rotates a few promotions automatically, with a pause button and reduced-motion support

Avoid when

Product photos need synced thumbnails, hover zoom and fullscreen → use Product Gallery instead
Logos or testimonials should scroll continuously without user navigation → use Marquee instead
Critical content sits on later slides; users rarely go past the first, so show it directly

Installation

node scripts/add.mjs carousel --out ./src/marvelous

KI-Agent mit dem MCP-Server von Marvelous UI: install_components({ slugs: ["carousel"], target_dir: "<absolute path>/src/marvelous", framework: "react" }).

Kopierte Dateien (inklusive Abhängigkeiten): tokens/tokens.css, core/base.css, core/dom.js, core/element.js, core/motion.js, components/carousel/carousel.js, components/carousel/carousel.css.

Verwendung

Referenz-Markup zum Starten und Anpassen mit Attributen, data-* und CSS-Variablen:

<div style="display:grid;gap:2rem;width:100%;max-width:44rem;margin-inline:auto">
  <mv-carousel id="carousel-demo-hero" label="Featured destinations" loop autoplay="5000">
    <article style="position:relative;display:grid;align-content:end;gap:.25rem;aspect-ratio:16/8;padding:1.5rem;border-radius:var(--mv-radius-xl);color:#fff;background:radial-gradient(120% 90% at 85% 10%,#ffd7a8 0,transparent 55%),linear-gradient(135deg,#f0845c,#b14a6d 60%,#5b2a6e)">
      <span style="font-size:.75rem;letter-spacing:.08em;text-transform:uppercase;opacity:.85">Portugal · 4 nights</span>
      <h3 style="margin:0;font-size:1.75rem;letter-spacing:-.02em">Lisbon</h3>
      <p style="margin:0;max-width:26rem;font-size:.875rem;opacity:.9">Yellow trams, miradouros and pastéis de nata at sunset.</p>
    </article>
    <article style="position:relative;display:grid;align-content:end;gap:.25rem;aspect-ratio:16/8;padding:1.5rem;border-radius:var(--mv-radius-xl);color:#fff;background:radial-gradient(110% 80% at 20% 0%,#ffc4d6 0,transparent 55%),linear-gradient(160deg,#e45f7f,#7d3c98 55%,#2c2a6b)">
      <span style="font-size:.75rem;letter-spacing:.08em;text-transform:uppercase;opacity:.85">Japan · 9 nights</span>
      <h3 style="margin:0;font-size:1.75rem;letter-spacing:-.02em">Kyoto</h3>
      <p style="margin:0;max-width:26rem;font-size:.875rem;opacity:.9">Wooden temples, the lanes of Gion and cherry blossoms in spring.</p>
    </article>
    <article style="position:relative;display:grid;align-content:end;gap:.25rem;aspect-ratio:16/8;padding:1.5rem;border-radius:var(--mv-radius-xl);color:#fff;background:radial-gradient(120% 90% at 80% 0%,#9ff3e1 0,transparent 50%),linear-gradient(150deg,#1f9c9a,#1d5f8a 55%,#16294f)">
      <span style="font-size:.75rem;letter-spacing:.08em;text-transform:uppercase;opacity:.85">Iceland · 6 nights</span>
      <h3 style="margin:0;font-size:1.75rem;letter-spacing:-.02em">Reykjavik</h3>
      <p style="margin:0;max-width:26rem;font-size:.875rem;opacity:.9">Northern lights, steaming lagoons and roads at the edge of the world.</p>
    </article>
    <article style="position:relative;display:grid;align-content:end;gap:.25rem;aspect-ratio:16/8;padding:1.5rem;border-radius:var(--mv-radius-xl);color:#fff;background:radial-gradient(120% 90% at 15% 10%,#ffe29a 0,transparent 55%),linear-gradient(140deg,#e89b3c,#c2553a 55%,#6b2b2b)">
      <span style="font-size:.75rem;letter-spacing:.08em;text-transform:uppercase;opacity:.85">Morocco · 5 nights</span>
      <h3 style="margin:0;font-size:1.75rem;letter-spacing:-.02em">Marrakech</h3>
      <p style="margin:0;max-width:26rem;font-size:.875rem;opacity:.9">Fragrant souks, hidden riads and mint tea on the rooftops.</p>
    </article>
  </mv-carousel>

  <mv-carousel id="carousel-demo-cards" label="Recent articles" controls="footer" style="--mv-carousel-per-view:3;--mv-carousel-gap:.75rem">
    <a href="#" style="display:grid;gap:.35rem;padding:1rem;border:1px solid var(--mv-border);border-radius:var(--mv-radius-lg);background:var(--mv-surface);color:inherit;text-decoration:none"><span style="font-size:.75rem;color:var(--mv-accent-fg);font-weight:600">Design</span><strong style="font-size:.9rem;line-height:1.3">Designing a token system that lasts</strong><span style="font-size:.75rem;color:var(--mv-fg-muted)">6 min read</span></a>
    <a href="#" style="display:grid;gap:.35rem;padding:1rem;border:1px solid var(--mv-border);border-radius:var(--mv-radius-lg);background:var(--mv-surface);color:inherit;text-decoration:none"><span style="font-size:.75rem;color:var(--mv-accent-fg);font-weight:600">Accessibility</span><strong style="font-size:.9rem;line-height:1.3">Visible focus, no compromises</strong><span style="font-size:.75rem;color:var(--mv-fg-muted)">4 min read</span></a>
    <a href="#" style="display:grid;gap:.35rem;padding:1rem;border:1px solid var(--mv-border);border-radius:var(--mv-radius-lg);background:var(--mv-surface);color:inherit;text-decoration:none"><span style="font-size:.75rem;color:var(--mv-accent-fg);font-weight:600">CSS</span><strong style="font-size:.9rem;line-height:1.3">Scroll snap: the carousel without JavaScript</strong><span style="font-size:.75rem;color:var(--mv-fg-muted)">8 min read</span></a>
    <a href="#" style="display:grid;gap:.35rem;padding:1rem;border:1px solid var(--mv-border);border-radius:var(--mv-radius-lg);background:var(--mv-surface);color:inherit;text-decoration:none"><span style="font-size:.75rem;color:var(--mv-accent-fg);font-weight:600">Performance</span><strong style="font-size:.9rem;line-height:1.3">Jank-free animation with transform</strong><span style="font-size:.75rem;color:var(--mv-fg-muted)">5 min read</span></a>
    <a href="#" style="display:grid;gap:.35rem;padding:1rem;border:1px solid var(--mv-border);border-radius:var(--mv-radius-lg);background:var(--mv-surface);color:inherit;text-decoration:none"><span style="font-size:.75rem;color:var(--mv-accent-fg);font-weight:600">Web Components</span><strong style="font-size:.9rem;line-height:1.3">Native forms with ElementInternals</strong><span style="font-size:.75rem;color:var(--mv-fg-muted)">7 min read</span></a>
    <a href="#" style="display:grid;gap:.35rem;padding:1rem;border:1px solid var(--mv-border);border-radius:var(--mv-radius-lg);background:var(--mv-surface);color:inherit;text-decoration:none"><span style="font-size:.75rem;color:var(--mv-accent-fg);font-weight:600">Motion</span><strong style="font-size:.9rem;line-height:1.3">Respecting prefers-reduced-motion</strong><span style="font-size:.75rem;color:var(--mv-fg-muted)">3 min read</span></a>
  </mv-carousel>
</div>

API

Attributes

Name	Typ	Default	Description
`label`	string		Accessible name of the region (aria-label).
`loop`	boolean		Wraps back to the start after the last slide (and vice versa).
`autoplay`	number (ms) \| boolean		Automatic scrolling (5000 ms if empty), with a play/pause button; disabled with reduced motion.
`orientation`	horizontal \| vertical	`horizontal`	Scroll direction (vertical: height via --mv-carousel-height).
`controls`	overlay \| footer	`overlay`	Arrows overlaid on the edges or grouped in the footer with the dots.
`no-controls`	boolean		Hides the arrows.
`no-dots`	boolean		Hides the dots.
`drag`	true \| false	`true`	Mouse drag (touch uses native scrolling).

Properties

Name	Typ	Description
`index`	number	Active page (setting it = goTo).
`length`	number	Number of slides.
`pages`	number	Number of positions (slides − per view + 1).
`playing`	boolean	Autoplay active (read-only).

Methods

Name	Description
`next() / prev()`	Next / previous slide.
`goTo(index, { smooth })`	Goes to a position.
`play() / pause()`	Controls autoplay.

Events

Name	Description
`mv-change`	detail: { index, slide } when the active position changes.

Content structure

Name	Description
`children`	Each child becomes a slide (role=group, “2 of 5”).

CSS classes

Name	Description
`mv-carousel-track / -slide / -arrow / -dots / -dot / -play`	Generated parts; data-active on the current slide.

CSS variables

Name	Default	Description
`--mv-carousel-per-view`	`1`	Slides visible at once (integer; can vary per media query).
`--mv-carousel-gap`	`var(--mv-space-4)`	Space between slides.
`--mv-carousel-height`	`20rem`	Height in vertical orientation.
`--mv-carousel-radius`	`0`	Track radius (clips slides while scrolling).

Accessibility

APG Carousel pattern: labeled region with aria-roledescription=“carousel”, slides are role=group with aria-roledescription=“slide” (“2 of 5”). Arrows and dots are named buttons (aria-current on the active dot). The track is focusable: ←/→ (↑/↓ when vertical), Home/End. Autoplay has a pause button and stops on hover and focus, off screen, in a hidden tab and with reduced motion; the track is aria-live=polite only when it is not auto-scrolling.