Carousel

Example

<section data-slean="carousel" aria-roledescription="carousel" aria-label="Native paths">
	<div data-slean-part="viewport" tabindex="0"
		data-slean-previous="Previous slide" data-slean-next="Next slide">
		<div data-slean-part="slide" role="group" aria-roledescription="slide" aria-label="1 of 4">
			<div class="panel">
				<h3>Dialog</h3>
				<p>A modal from &lt;dialog&gt; and two buttons with commandfor.</p>
				<a href="/primitives/dialog">Read the dialog page</a>
			</div>
		</div>
		<div data-slean-part="slide" role="group" aria-roledescription="slide" aria-label="2 of 4">
			<div class="panel">
				<h3>Popover</h3>
				<p>The top layer, light dismiss and focus return from one attribute.</p>
				<a href="/primitives/popover">Read the popover page</a>
			</div>
		</div>
		<div data-slean-part="slide" role="group" aria-roledescription="slide" aria-label="3 of 4">
			<div class="panel">
				<h3>Accordion</h3>
				<p>One open item at a time from a shared name on details elements.</p>
				<a href="/primitives/accordion">Read the accordion page</a>
			</div>
		</div>
		<div data-slean-part="slide" role="group" aria-roledescription="slide" aria-label="4 of 4">
			<div class="panel">
				<h3>Date field</h3>
				<p>Segmented entry, validation and a picker in one input element.</p>
				<a href="/primitives/date-field">Read the date field page</a>
			</div>
		</div>
	</div>
</section>

<script lang="ts">
	import '@svelte-lean/styles/carousel.css';
</script>

<section data-slean="carousel" aria-roledescription="carousel" aria-label="Native paths">
	<div data-slean-part="viewport" tabindex="0"
		data-slean-previous="Previous slide" data-slean-next="Next slide">
		<div data-slean-part="slide" role="group" aria-roledescription="slide" aria-label="1 of 4">
			<div class="panel">
				<h3>Dialog</h3>
				<p>A modal from &lt;dialog&gt; and two buttons with commandfor.</p>
				<a href="/primitives/dialog">Read the dialog page</a>
			</div>
		</div>
		<div data-slean-part="slide" role="group" aria-roledescription="slide" aria-label="2 of 4">
			<div class="panel">
				<h3>Popover</h3>
				<p>The top layer, light dismiss and focus return from one attribute.</p>
				<a href="/primitives/popover">Read the popover page</a>
			</div>
		</div>
		<div data-slean-part="slide" role="group" aria-roledescription="slide" aria-label="3 of 4">
			<div class="panel">
				<h3>Accordion</h3>
				<p>One open item at a time from a shared name on details elements.</p>
				<a href="/primitives/accordion">Read the accordion page</a>
			</div>
		</div>
		<div data-slean-part="slide" role="group" aria-roledescription="slide" aria-label="4 of 4">
			<div class="panel">
				<h3>Date field</h3>
				<p>Segmented entry, validation and a picker in one input element.</p>
				<a href="/primitives/date-field">Read the date field page</a>
			</div>
		</div>
	</div>
</section>

<style>
	.panel {
		block-size: 100%;
		padding: 1.5rem;
		border-radius: 0.625rem;
		background: var(--slean-muted);
	}
</style>

Why this implementation exists

Most of a carousel is scrolling: a row wider than its box, moved by touch, trackpad or keys, stopping on a slide. Scroll snapping does that in every browser, and a focusable viewport gives the keyboard the same. Component libraries rebuild it with transforms and pointer handlers and then have to rebuild momentum, snapping and keyboard support too.

The rest, buttons and markers, is now CSS as well. ::scroll-button() asks the browser for a button that scrolls the viewport and disables itself at the end; ::scroll-marker asks for one marker per slide in a group the browser exposes as tabs. Chrome ships them; Firefox and Safari do not yet, and there the carousel stays a snapping row. Svelte Lean adds no script to fill that gap: the content is reachable either way.

Usage

The markup needs no package. Install @svelte-lean/styles for the stylesheet; @svelte-lean/primitives adds the typed contract and nothing at runtime.

npm install @svelte-lean/styles

pnpm add @svelte-lean/styles

yarn add @svelte-lean/styles

bun add @svelte-lean/styles

import '@svelte-lean/styles/carousel.css';

Name the root with aria-label, give the viewport tabindex="0", and give each slide role="group", aria-roledescription="slide" and its position as a label in the page language. Name the generated buttons with data-slean-previous and data-slean-next on the viewport; without them the browser names them in the language of its own interface.

The stylesheet sets container-type: scroll-state on the viewport and the slides to fade a button that cannot scroll and fill the marker of the snapped slide. If your CSS sets another container type on a slide, keep scroll-state in the list.

Anatomy

Runtime profile

Tier 0: the carousel has no behavior module, the Vite plugin maps carousel to no module, and the native-only fixture proves the path ships no Svelte Lean JavaScript. The buttons and markers are pseudo-elements the browser creates from carousel.css.

Accessibility contract

• The root is a region named by its label with the role description carousel; each slide is a group with the role description slide and a label such as 1 of 4.
• The viewport is focusable, so ArrowLeft and ArrowRight scroll it in every browser; Tab moves into the slides and the browser scrolls a focused link into view.
• In Chrome the markers are exposed as tabs named after the slides, the current one selected, and the arrow keys move between them; the buttons are named buttons that the browser disables at the ends. The stylesheet asks for tabs with scroll-marker-group: after tabs; the default mode, links, is exposed by Chrome 154 as a navigation of links.
• No autoplay: moving content needs a pause control and a stop on hover and focus, which would make the carousel a Tier 2 behavior. No live region either, since scrolling changes no content.

Keyboard

Platform features

Without JavaScript

Fully functional, including the generated buttons and markers in Chrome.

Server rendering

Static HTML. The first slide is in view on load.

Before hydration

Nothing is attached; scrolling, snapping and the generated controls work before hydration.

Styling

carousel.css lays out the row and its snap points, hides the scrollbar where the buttons and markers exist, places the buttons at the ends of the marker row, draws their chevrons as two background strokes in a rotated circle (mirrored under :dir(rtl)), and uses scroll-state container queries for the faded button and the filled, wider marker. The tokens it reads:

State selectors the stylesheet targets, all from the platform or ARIA: ::scroll-button(*), ::scroll-button(inline-end), ::scroll-button(inline-start), ::scroll-marker, ::scroll-marker-group, :dir(rtl).

Variant attributes: data-slean-previous; data-slean-next.

Compatibility notes

Scroll snapping is Baseline 2020 and widely available. ::scroll-button(), ::scroll-marker and ::scroll-marker-group are in Chrome 135 and not in Firefox or Safari at the time of writing; container scroll-state queries, used only to style them, are in Chrome 133. Elsewhere the viewport keeps its scrollbar and the arrow keys, touch and trackpad move it.

Examples

Several slides per view

A slide is as wide as the viewport by default. Set a narrower flex-basis on the slides in the application's CSS; snapping still aligns a slide's start, and the generated buttons scroll one viewport width at a time.

/* Application CSS: slides narrower than the viewport. Snapping still aligns a slide's start,
 * and the generated buttons scroll one viewport width at a time. */
.projects [data-slean-part='slide'] {
	flex-basis: min(18rem, 80%);
}

Testing

• apps/playground/tests/primitives/display.spec.ts Playwright: open state, exclusive groups, stretched links, roles and names, carousel scrolling, axe
• packages/styles/tests static checks of the stylesheet (layers, tokens, specificity, dark parity)

Source

• packages/primitives/src/carousel/contract.md the contract in prose: semantics, keyboard, focus, ARIA, SSR, JS-disabled behavior
• packages/primitives/src/carousel/contract.ts typed constants: name, tier, base, parts, options, events
• packages/styles/css/carousel.css the optional stylesheet