Primitives Layout and display
Carousel
A row of slides that scrolls and snaps, for featured content or a gallery; where CSS carousels exist the browser adds the buttons and markers.
Markdown version of this page, for assistants (Markdown for AI)
On this page
A modal from <dialog> and two buttons with commandfor.
The top layer, light dismiss and focus return from one attribute.
One open item at a time from a shared name on details elements.
Typed entry, validation and a picker from one input of type date.
Code
<script lang="ts">
import '@svelte-lean/styles/carousel.css';
const slides = [
{ title: 'Dialog', text: 'A modal from <dialog> and two buttons with commandfor.' },
{ title: 'Popover', text: 'The top layer, light dismiss and focus return from one attribute.' },
{ title: 'Accordion', text: 'One open item at a time from a shared name on details elements.' },
{ title: 'Date input', text: 'Typed entry, validation and a picker from one input of type date.' }
];
</script>
<section data-slean="carousel" aria-roledescription="carousel" aria-label="Native paths">
<!-- svelte-ignore a11y_no_noninteractive_tabindex -->
<div
data-slean-part="viewport"
tabindex="0"
data-slean-previous="Previous slide"
data-slean-next="Next slide"
>
{#each slides as slide, i (slide.title)}
<div
data-slean-part="slide"
role="group"
aria-roledescription="slide"
aria-label="{i + 1} of {slides.length}"
>
<div class="panel">
<strong>{slide.title}</strong>
<p>{slide.text}</p>
</div>
</div>
{/each}
</div>
</section>
<style>
.panel {
display: grid;
align-content: start;
gap: 0.5rem;
block-size: 100%;
min-block-size: 10rem;
padding: 1.5rem;
border-radius: var(--slean-radius-lg);
background: var(--slean-muted);
}
.panel p {
margin: 0;
color: var(--slean-fg-muted);
}
</style>Examples
Gallery
Code
<script lang="ts">
import '@svelte-lean/styles/carousel.css';
const photos = [
{ name: 'Harbor at dawn', tint: 'linear-gradient(160deg, #f6d365, #fda085)' },
{ name: 'Glacier lake', tint: 'linear-gradient(160deg, #a1c4fd, #4f7fd6)' },
{ name: 'Pine ridge', tint: 'linear-gradient(160deg, #96e6a1, #2f8f5b)' },
{ name: 'Desert road', tint: 'linear-gradient(160deg, #fbc2a4, #b4543a)' },
{ name: 'Night market', tint: 'linear-gradient(160deg, #6a5acd, #1e1b4b)' }
];
</script>
<section data-slean="carousel" aria-roledescription="carousel" aria-label="Photos">
<!-- svelte-ignore a11y_no_noninteractive_tabindex -->
<div
data-slean-part="viewport"
tabindex="0"
data-slean-previous="Previous photo"
data-slean-next="Next photo"
>
{#each photos as photo, i (photo.name)}
<div
data-slean-part="slide"
role="group"
aria-roledescription="slide"
aria-label="{i + 1} of {photos.length}"
>
<figure>
<div class="photo" style:background={photo.tint}></div>
<figcaption>{photo.name}</figcaption>
</figure>
</div>
{/each}
</div>
</section>
<style>
figure {
margin: 0;
}
.photo {
aspect-ratio: 21 / 9;
border-radius: var(--slean-radius-lg);
}
figcaption {
padding-block: 0.5rem 0;
color: var(--slean-fg-muted);
font-size: var(--slean-text-sm);
}
</style>Several slides per view
One project and the community forum.
Unlimited projects, roles and audit logs.
Single sign-on and a support contract.
Dedicated region and a named contact.
Team features for schools and courses.
Code
<script lang="ts">
import '@svelte-lean/styles/carousel.css';
const plans = [
{ name: 'Starter', price: '$0', text: 'One project and the community forum.' },
{ name: 'Team', price: '$12', text: 'Unlimited projects, roles and audit logs.' },
{ name: 'Business', price: '$29', text: 'Single sign-on and a support contract.' },
{ name: 'Enterprise', price: 'Custom', text: 'Dedicated region and a named contact.' },
{ name: 'Education', price: '$0', text: 'Team features for schools and courses.' }
];
</script>
<section data-slean="carousel" aria-roledescription="carousel" aria-label="Plans">
<!-- svelte-ignore a11y_no_noninteractive_tabindex -->
<div
data-slean-part="viewport"
tabindex="0"
data-slean-previous="Previous plans"
data-slean-next="Next plans"
>
{#each plans as plan, i (plan.name)}
<div
class="plan"
data-slean-part="slide"
role="group"
aria-roledescription="slide"
aria-label="{i + 1} of {plans.length}"
>
<strong>{plan.name}</strong>
<span class="price">{plan.price}</span>
<p>{plan.text}</p>
</div>
{/each}
</div>
</section>
<style>
/* Narrower slides show several per view; snapping still aligns a slide's start. */
.plan {
flex-basis: min(14rem, 80%);
display: grid;
align-content: start;
gap: 0.25rem;
padding: 1.25rem;
border: 1px solid var(--slean-border);
border-radius: var(--slean-radius-lg);
}
.price {
font-size: var(--slean-text-lg);
font-weight: 600;
}
.plan p {
margin: 0;
color: var(--slean-fg-muted);
font-size: var(--slean-text-sm);
}
</style>Usage
Plain markup with a stylesheet: install @svelte-lean/styles. No JavaScript runs.
npm install @svelte-lean/stylespnpm add @svelte-lean/stylesyarn add @svelte-lean/stylesbun add @svelte-lean/stylesimport '@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; otherwise the browser names them in its own interface language.
The stylesheet sets container-type: scroll-state on the viewport and the slides. If your CSS sets another container type on a slide, keep scroll-state in the list.
Anatomy
| Part | Element | data-slean-part | Required | Notes |
|---|---|---|---|---|
| root | <section data-slean="carousel" aria-roledescription="carousel"> | – | yes | Named with aria-label or aria-labelledby. |
| viewport | <div tabindex="0"> | viewport | yes | The scroll container. data-slean-previous and data-slean-next name the generated buttons. |
| slide | <div role="group" aria-roledescription="slide"> | slide | yes | aria-label with its position, such as "1 of 4"; its marker takes that name. |
Keyboard
| Key | When | Result |
|---|---|---|
| ArrowLeft/ArrowRight | focus on the viewport | Scrolls; snapping settles on a slide (native, every browser) |
| Enter/Space | focus on a generated button (Chromium) | Scrolls one page of the viewport (native) |
| ArrowLeft/ArrowRight | focus on a marker (Chromium) | Moves to the neighbouring marker and scrolls to its slide (native) |
Styling
carousel.css lays out the row and its snap points, hides the scrollbar where the buttons and markers exist, draws the chevrons (mirrored under :dir(rtl)), and uses scroll-state container queries for the faded button and the filled marker. data-color on the root or an ancestor colors the current marker (primary by default). The tokens it reads:
| Token | Default (light) | Applies to |
|---|---|---|
--slean-fg | var(--slean-neutral-12) | color |
--slean-space-4 | calc(var(--slean-spacing) * 4) | gap |
--slean-radius-lg | calc(var(--slean-radius) * 1.4) | border-radius |
--slean-space-3 | calc(var(--slean-spacing) * 3) | margin-block-start |
--slean-radius-full | 9999px | border-radius |
--slean-border-strong | var(--slean-neutral-8) | background |
--slean-duration-fast | 100ms | transition |
--slean-ease | cubic-bezier(0.2, 0, 0, 1) | transition |
--slean-color-main | var(--slean-primary-main) | background-color |
--slean-icon-chevron-left | url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Cpath d='M10 4L6 8l4 4' stroke='black' stroke-width='1.5' stroke-linecap='round' stroke-linejoin='round' fill='none'/%3E%3C/svg%3E") | mask |
--slean-icon-chevron-right | url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Cpath d='M6 4l4 4-4 4' stroke='black' stroke-width='1.5' stroke-linecap='round' stroke-linejoin='round' fill='none'/%3E%3C/svg%3E") | mask-image |
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.
Under the hood
Runtime and size
- Tier
- 0 · Native
- Behavior JS
- 0 B brotli · 0 B gzip ·
fixtures/· methodresults.json (native-only) - Platform features
scroll-snap,::scroll-button(),::scroll-marker,::scroll-marker-group,scroll-state queries- Shared listeners
- none
- Per-instance listeners
- none
- Lazy state
- none
- Native base
scroll-snap, ::scroll-button(), ::scroll-marker
Tier 0: no behavior module, the Vite plugin maps carousel to no module, and the native-only fixture proves the path ships no Svelte Lean JavaScript. Scrolling, snapping and the generated controls are the browser's; the buttons and markers are pseudo-elements it creates from carousel.css.
Why this implementation
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. Libraries that rebuild it with transforms and pointer handlers have to rebuild momentum, snapping and keyboard support too.
The buttons and markers are 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, exposed as tabs. Chrome ships them; in Firefox and Safari the carousel stays a snapping row, and Svelte Lean adds no script to fill the gap: the content is reachable either way. There is no autoplay.
The browser owns
- scrolling, snapping, touch and trackpad swipes, arrow keys on the focused viewport
- scrolling a focused element inside a slide into view
- in Chromium: the previous and next buttons, one marker per slide, their roles, names, keyboard and disabled state
Svelte Lean owns
- carousel.css: the snapping row, markers requested as tabs, the button and marker layout, the drawn chevrons, the faded button and the filled marker
- the contract: roles, labels, the names of the buttons, and why there is no autoplay
- documentation
Accessibility
- 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 tabs named after the slides, the current one selected, and the arrow keys move between them; the buttons are named buttons 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.
Platform features
| Feature | Baseline | Outside the target |
|---|---|---|
Scroll snap | Baseline 2020, widely available | Not applicable within the support policy |
::scroll-button(), ::scroll-marker, ::scroll-marker-group | Chrome 135; not in Firefox or Safari at the time of writing | No buttons and no markers; the viewport keeps its scrollbar |
scroll-marker-group: after tabs | Chrome 151 parses the keyword; Chrome 154 exposes the default, links, as a navigation of links | The declaration is dropped and scroll-marker-group: after applies |
Container scroll-state queries | Chrome 133 | Not used: the buttons and markers they style do not exist there |
:dir() | Baseline 2023, widely available | Not applicable within the support policy |
Without JavaScript
Fully functional, including the generated buttons and markers in Chrome.
Server rendering and hydration
Static HTML. The first slide is in view on load.
Nothing is attached; scrolling, snapping and the generated controls work before hydration.
Compatibility
Scroll snapping is Baseline 2020. ::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.
Tests and source
apps/playground/tests/primitives/display.spec.tsPlaywright: open state, exclusive groups, stretched links, roles and names, carousel scrolling, axepackages/styles/testsstatic checks of the stylesheet (layers, tokens, specificity, dark parity)
packages/primitives/src/carousel/contract.mdthe contract in prose: semantics, keyboard, focus, ARIA, SSR, JS-disabled behaviorpackages/primitives/src/carousel/contract.tstyped constants: name, tier, base, parts, options, eventspackages/styles/css/carousel.cssthe optional stylesheet