Carousel 1.2.2

The <velin-carousel> Web Component provides a touch-friendly slideshow with prev/next controls, dot indicators, optional autoplay with a pause control, and keyboard navigation. Deutsch: Karussell

Maturity: Documented as stable in VelinStyle 1.2.0. Design Intelligence (plan / review / agent meta) is separate and beta / foundation where noted.

When to use

Rotating hero media, product galleries, or testimonials where one slide is primary at a time.
When you need built-in prev/next, dots, swipe, and optional autoplay with an explicit pause control.

When not

Content that must all be visible for comprehension — use a static grid or list instead.
Fullscreen media lightbox browsing — use Lightbox.
Do not invent undocumented slide attributes; pass plain children as slides.

Basic Example

Slide 1

Slide 2

Slide 3

<velin-carousel>
  <div>Slide 1</div>
  <div>Slide 2</div>
  <div>Slide 3</div>
</velin-carousel>

Autoplay

Add the autoplay attribute. Set interval in milliseconds with interval (default 5000). A Pause / Play button appears in the indicator row (see pause control).

<velin-carousel autoplay interval="3000">
  <div>Slide 1</div>
  <div>Slide 2</div>
</velin-carousel>

Keyboard navigation

When focus is inside the carousel, arrow keys move between slides.

Key	Action
`Arrow Left` / `Arrow Right`	Previous / next slide
`Home` / `End`	First / last slide

Pause control

With autoplay, a pause button is added next to the dot indicators. It toggles aria-pressed, updates its label between “Pause automatic slide show” and “Resume automatic slide show”, and stops the timer until pressed again. Autoplay also pauses while the carousel is hovered or contains focus.

Accessibility

Host has role="region" and aria-roledescription="carousel"; the slide track is a role="group".
Each slide gets aria-roledescription="slide" and aria-label="Slide N of M"; inactive slides use aria-hidden="true" and inert.
Prev/next controls use descriptive aria-labels and meet the 2.75×2.75 rem minimum target size (WCAG 2.5.8).
Dot indicators are <button> elements with aria-label="Go to slide N" and aria-current on the active slide.
Autoplay includes an explicit pause/play control (WCAG 2.2.2) and pauses on hover or when focus enters the carousel.
Track transitions respect prefers-reduced-motion: reduce; touch swipe threshold is 50 px.

CSS Variables

Variable	Description
`--velin-color-surface-bright`	Control button background
`--velin-color-border`	Control button border
`--velin-color-primary`	Active dot indicator
`--velin-shadow-md`	Control button shadow
`--velin-color-focus`	Focus ring colour

API

Attributes

Attribute	Type	Description
`autoplay`	Boolean	Observed — enable auto-advancing slides
`interval`	Number	Observed — milliseconds between slides (default 5000)

Methods & events

API	Description
`prev()` / `next()`	Move one slide
`goTo(index)`	Zero-based slide index
`velin-slide-change`	Bubbles with `detail: { index }`

Parts

track, controls, prev, next, indicators. Default slot = slides.

Best practices & pitfalls

Prefer autoplay only when a pause control is acceptable; the component adds one when autoplay is set.
Keep slide content self-contained; inactive slides are inert / aria-hidden.
Do not rely on inventing Bootstrap carousel class names — this is the WC API only.