[FEE-11300] CSS Carousel Primitives
INFO
Build a fully functional carousel in pure CSS, with zero JavaScript: dot indicators, prev/next buttons, keyboard navigation, and touch support.
Limited Availability
Currently supported in Chrome 135+ and Edge 135 only. Not yet available in Firefox or Safari. Check the MDN compatibility table before using in production. A JavaScript polyfill or progressive enhancement fallback is REQUIRED for cross-browser support.
Context
Carousels are one of the most common UI patterns on the web. They are also one of the most difficult to implement correctly.
A production-quality carousel requires all of the following:
- Scroll tracking: detecting which slide is currently in view as the user scrolls or swipes
- Dot indicators: creating indicator elements and updating their active state in sync with scroll position
- Prev/next button state: disabling the "previous" button at the start, disabling the "next" button at the end
- Keyboard navigation: allowing users to navigate with arrow keys
- Touch/swipe support: handling touchstart, touchmove, touchend with velocity calculations
- ARIA attributes: marking roles, aria-label, aria-current, aria-disabled for screen readers
A hand-rolled carousel without a library means writing custom code for every item above: scroll tracking, indicator sync, button state, keyboard handling, touch gestures, and ARIA wiring. Reaching for a library removes that maintenance burden but adds JavaScript weight to the page:
- Swiper: the most feature-complete option, and the heaviest of the four. Its full bundle (swiper-bundle.min.js) is roughly 47 KB gzipped and about 150 KB minified.
- Splide: a lighter alternative covering a similar feature set.
- Embla Carousel: deliberately minimal; dot and button wiring is left to the developer.
- Keen Slider: deliberately minimal, comparable in scope to Embla.
These libraries are correct and well-maintained. The question is why the browser cannot provide this capability natively.
The browser already handles all of the equivalent complexity for native interactive controls:
<input>: keyboard navigation, focus management, ARIA state, system styling<select>: dropdown positioning, keyboard selection, scroll behavior, accessibility<details>/<summary>: open/close toggle, keyboard support, ARIA expanded state
Scroll containers are among the most interactive surfaces on the page. Yet they have no native controls for indicators, buttons, or discrete snap-point awareness. CSS Carousel Primitives address this gap directly.
You are building a product image gallery for an e-commerce page. The gallery shows one image at a time with dot indicators and prev/next navigation. The requirements are:
- Works with touch/swipe on mobile (no JS)
- Keyboard-navigable for accessibility
- Dots highlight the currently visible image
- Prev button is disabled when on the first image; Next is disabled at the last
- No third-party JavaScript carousel library
- The entire feature must work within a static HTML + CSS page (no build step, no bundler)
Before CSS Carousel Primitives, meeting all these requirements simultaneously was impossible without JavaScript. Using ::scroll-marker, ::scroll-button(), and scroll snapping, CSS now satisfies this specific requirement set directly.
The primitives cover the six requirements above and nothing more. They do not provide autoplay, infinite or looping scroll, or a programmatic API to control the carousel from script. A gallery that needs to auto-advance or loop back to the first slide after the last still needs JavaScript in addition to, or instead of, these primitives.
Visual
| CSS primitive | What the browser handles automatically |
|---|---|
scroll-snap-type / scroll-snap-align | Snap physics: settles the scroll position on a slide boundary after a swipe, drag, or scroll, regardless of gesture velocity. |
::scroll-marker | Creates one focusable indicator per snap target, inserts it into the marker group, and applies :target-current to the marker whose slide is in view. |
::scroll-button() | Creates a previous/next control, disables it at the corresponding scroll boundary, and scrolls one snap point on click or keyboard activation. |
scroll-marker-group | Positions the generated ::scroll-marker-group before or after the scroll container and groups the markers into a tablist-like composite widget. |
Example
Full Carousel: Dots and Prev/Next Buttons
The following example is a fully functional image carousel in pure HTML and CSS. Copy and open it directly in Chrome 135+ or Edge 135+.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>CSS Carousel Primitives</title>
<style>
body {
font-family: system-ui, sans-serif;
padding: 24px;
background: #f5f5f5;
}
/* ── Feature detection wrapper ────────────────────── */
@supports (scroll-marker-group: after) {
/* ── Carousel container ───────────────────────────── */
.carousel {
position: relative;
overflow-x: auto;
scroll-snap-type: x mandatory;
scroll-marker-group: after;
display: flex;
border-radius: 12px;
max-width: 640px;
margin: 0 auto;
/* Smooth scroll for button clicks */
scroll-behavior: smooth;
}
/* ── Each slide ───────────────────────────────────── */
.carousel img {
scroll-snap-align: start;
flex-shrink: 0;
width: 100%;
aspect-ratio: 3 / 2;
object-fit: cover;
display: block;
}
/* ── Scroll marker group (dot indicator bar) ─────── */
.carousel::scroll-marker-group {
display: flex;
justify-content: center;
align-items: center;
gap: 8px;
padding: 10px 0 4px;
}
/* ── Individual dot ───────────────────────────────── */
.carousel img::scroll-marker {
content: '';
width: 10px;
height: 10px;
border-radius: 50%;
background: #ccc;
border: 2px solid transparent;
outline: 2px solid transparent;
outline-offset: 2px;
cursor: pointer;
transition: background 0.2s, transform 0.2s;
}
/* ── Active dot ───────────────────────────────────── */
/* :target-current is true for the ::scroll-marker whose slide is currently in view */
.carousel img::scroll-marker:target-current {
background: #1a1a2e;
transform: scale(1.2);
}
/* ── Focus ring on dot ────────────────────────────── */
.carousel img::scroll-marker:focus-visible {
outline: 2px solid #0066cc;
}
/* ── Prev / Next buttons ──────────────────────────── */
.carousel::scroll-button(inline-start),
.carousel::scroll-button(inline-end) {
position: absolute;
top: 50%;
transform: translateY(-50%);
width: 36px;
height: 36px;
border: none;
border-radius: 50%;
background: rgba(0, 0, 0, 0.55);
color: white;
font-size: 1rem;
line-height: 1;
cursor: pointer;
display: flex;
align-items: center;
justify-content: center;
transition: background 0.15s;
}
.carousel::scroll-button(inline-start) {
content: '←' / 'Previous slide';
left: 8px;
}
.carousel::scroll-button(inline-end) {
content: '→' / 'Next slide';
right: 8px;
}
/* ── Hover state ──────────────────────────────────── */
.carousel::scroll-button(inline-start):hover,
.carousel::scroll-button(inline-end):hover {
background: rgba(0, 0, 0, 0.8);
}
/* ── Disabled state (at scroll boundary) ─────────── */
.carousel::scroll-button(inline-start):disabled,
.carousel::scroll-button(inline-end):disabled {
opacity: 0.3;
cursor: not-allowed;
}
/* ── Focus ring on buttons ────────────────────────── */
.carousel::scroll-button(inline-start):focus-visible,
.carousel::scroll-button(inline-end):focus-visible {
outline: 2px solid #0066cc;
outline-offset: 2px;
}
/* ── Reduced motion ───────────────────────────────── */
@media (prefers-reduced-motion: reduce) {
.carousel {
scroll-behavior: auto;
}
.carousel img::scroll-marker {
transition: none;
}
}
} /* end @supports */
/* ── Fallback for non-supporting browsers ─────────── */
@supports not (scroll-marker-group: after) {
.carousel {
display: flex;
overflow-x: auto;
scroll-snap-type: x mandatory;
max-width: 640px;
margin: 0 auto;
border-radius: 12px;
}
.carousel img {
scroll-snap-align: start;
flex-shrink: 0;
width: 100%;
aspect-ratio: 3 / 2;
object-fit: cover;
}
.unsupported-notice {
text-align: center;
margin-top: 12px;
color: #888;
font-size: 0.875rem;
}
}
</style>
</head>
<body>
<div class="carousel" aria-label="Product image gallery">
<img src="https://picsum.photos/seed/1/600/400" alt="Slide 1">
<img src="https://picsum.photos/seed/2/600/400" alt="Slide 2">
<img src="https://picsum.photos/seed/3/600/400" alt="Slide 3">
<img src="https://picsum.photos/seed/4/600/400" alt="Slide 4">
<img src="https://picsum.photos/seed/5/600/400" alt="Slide 5">
</div>
<p class="unsupported-notice">
Swipe or scroll to view all images. Dot indicators and prev/next buttons require Chrome 135+.
</p>
</body>
</html>What you get with zero JavaScript:
- Swipe left/right on touch screens
- Click dots to jump to any slide
- Click the arrow buttons to step forward or backward
- Arrow buttons auto-disable at the first and last slide
- Arrow key navigation when dots have focus
prefers-reduced-motionrespected automatically
Minimal version (no @supports wrapper)
For internal tools or Chrome-only environments where you control the browser, the minimum viable CSS is:
.carousel {
overflow-x: auto;
scroll-snap-type: x mandatory;
scroll-marker-group: after;
display: flex;
scroll-behavior: smooth;
}
.carousel img {
scroll-snap-align: start;
flex-shrink: 0;
width: 100%;
}
.carousel::scroll-marker-group {
display: flex;
gap: 8px;
justify-content: center;
padding: 8px 0;
}
.carousel img::scroll-marker {
content: '';
width: 10px;
height: 10px;
border-radius: 50%;
background: #ccc;
}
.carousel img::scroll-marker:target-current {
background: #333;
}
.carousel::scroll-button(inline-start) { content: '←' / 'Previous slide'; }
.carousel::scroll-button(inline-end) { content: '→' / 'Next slide'; }The content property on ::scroll-button() is required. Without it, the pseudo-element does not render.
Best Practices
- MUST include visible focus styles on
::scroll-button()pseudo-elements. Keyboard users rely on prev/next controls for navigation, and invisible focus is an accessibility failure. - MUST give every
::scroll-button()an accessible name via generated-content alt text (content: '←' / 'Previous slide') or an equivalentaria-label. A bare arrow glyph announces nothing useful to a screen reader. - MUST add
scroll-snap-typeon the container andscroll-snap-alignon each item. Without scroll snapping, scroll markers do not correspond to discrete positions and the feature behaves unpredictably. - SHOULD use
@supports (scroll-marker-group: after)to gate the CSS carousel features and provide a fallback (static image strip or JS carousel) for browsers that do not support the primitives. - MUST NOT ship CSS Carousel Primitives to production without a JavaScript polyfill or progressive enhancement strategy for Firefox and Safari. As of 2026, shipped support is Chrome/Edge only.
- SHOULD use
@media (prefers-reduced-motion: reduce)to disable scroll animations while keeping markers and buttons fully functional. The user still needs to navigate, just without motion. - SHOULD provide a visible label or
aria-labelon the scroll container to communicate its purpose to assistive technology. - SHOULD use
object-fit: coverand a fixedaspect-ratioon carousel images to prevent layout shift between images of different natural sizes.
Design Thinking
Why carousels needed JavaScript
Until CSS Carousel Primitives, CSS had no mechanism to:
- Know the current scroll position: CSS cannot observe which snap target is currently in the viewport. JavaScript listens to
scrollevents and usesIntersectionObserverto detect the active slide. - Create indicator elements that respond to scroll state: dot indicators are regular DOM elements (usually
<button>tags) that JavaScript updates by adding/removing active class names. CSS had no pseudo-element that could exist and receive state from a separate scroll container. - Programmatically scroll to a snap point: JavaScript calls
element.scrollTo()when the user clicks a dot or a button. CSS cannot trigger scrolling in response to a click, outside of:targetanchor hacks, which are fragile.
How Swiper.js solved it
Swiper.js implements a complete JavaScript carousel:
- Attaches
pointermoveandtouchmoveevent listeners to track swipe velocity and direction - Maintains an internal index of the active slide
- On slide change: removes
swiper-slide-activefrom the previous dot, adds it to the next dot - Renders prev/next buttons as real
<button>DOM elements and wiresclicklisteners - Adds
aria-labelandaria-currentdynamically via JavaScript
This is correct behavior: Swiper.js handles every edge case, at the cost of the JavaScript runtime, the DOM manipulation overhead, and the bundle weight.
CSS-first philosophy
The browser's native controls (<input>, <select>, <details>) are correct because the browser handles all the complexity internally. The developer declares intent in HTML and CSS; the browser handles scroll physics, keyboard events, focus management, and ARIA semantics.
CSS Carousel Primitives apply the same philosophy to scroll containers:
::scroll-marker: the browser creates and manages indicator elements, wires their active state to scroll position, and routes keyboard focus automatically::scroll-button(): the browser creates and manages prev/next controls, handles disabled state at scroll boundaries, and fires scroll events on clickscroll-snap-type/scroll-snap-align: the browser handles snap physics, touch velocity, and discrete-position snapping
Deep Dive
::scroll-marker: how it works
::scroll-marker is a pseudo-element that can be declared on any scroll snap target inside a scroll container. When declared, the browser creates a focusable indicator element and inserts it into the ::scroll-marker-group.
The key behavior: the browser tracks which snap target is currently in the scroll container's visible area and applies :target-current to the corresponding ::scroll-marker automatically. This eliminates the IntersectionObserver + class-toggling pattern that every JavaScript carousel implements.
The content property must be set (even to '') for the marker to be rendered. Without content, the pseudo-element is not generated.
:target-current: the active-state pseudo-class
:target-current is a new pseudo-class introduced alongside CSS Carousel Primitives. It applies to the ::scroll-marker whose corresponding snap target is currently intersecting the scroll container's snap viewport.
Do not confuse it with:
:target: applies to the element matched by the URL fragment (e.g.,#slide-1):checked: applies to checked form controls:focus: applies to the currently focused element
:target-current is specifically for the "currently active snap target" concept and is only valid on ::scroll-marker pseudo-elements.
scroll-marker-group: placement property
scroll-marker-group: after positions the ::scroll-marker-group pseudo-element after the scroll container's content in the normal document flow: below the images in a horizontal carousel.
scroll-marker-group: before positions it before, which is useful for vertical carousels where you want the indicator to appear at the top.
The ::scroll-marker-group itself is a flex container by default and can be styled with standard layout properties.
::scroll-button(): the direction argument
::scroll-button() accepts a logical direction keyword:
inline-start: the "previous" button (left in LTR, right in RTL)inline-end: the "next" button (right in LTR, left in RTL)block-start: scroll up (for vertical containers)block-end: scroll down (for vertical containers)
Using logical keywords (inline-start / inline-end) rather than physical keywords (left / right) ensures correct behavior in right-to-left writing modes automatically.
The browser automatically:
- Disables
::scroll-button(inline-start)when the scroll container is at its start boundary - Disables
::scroll-button(inline-end)when at its end boundary - Fires a scroll event on click, advancing by one snap point
- Routes keyboard Enter/Space events to the appropriate scroll action
Keyboard navigation behavior
The ::scroll-marker-group receives focus as a composite widget. Once focused:
- Arrow Left / Arrow Right (or Arrow Up / Down for vertical) moves focus between markers
- The focused marker's corresponding snap target scrolls into view
- Tab moves focus out of the marker group to the next focusable element in the page
The marker group reports its role to assistive technology as a tablist, and its arrow-key behavior follows the focusgroup pattern, the standard for composite widgets where arrow keys move focus among a set of related controls.
Progressive enhancement: recommended pattern
/* Base styles: static strip for all browsers */
.carousel {
display: flex;
overflow-x: auto;
scroll-snap-type: x mandatory;
max-width: 640px;
}
.carousel img {
scroll-snap-align: start;
flex-shrink: 0;
width: 100%;
aspect-ratio: 3 / 2;
object-fit: cover;
}
/* Enhanced carousel: markers and buttons where supported */
@supports (scroll-marker-group: after) {
.carousel {
scroll-marker-group: after;
scroll-behavior: smooth;
}
.carousel::scroll-marker-group {
display: flex;
gap: 8px;
justify-content: center;
padding: 8px 0;
}
.carousel img::scroll-marker {
content: '';
width: 10px;
height: 10px;
border-radius: 50%;
background: #ccc;
}
.carousel img::scroll-marker:target-current {
background: #333;
}
.carousel::scroll-button(inline-start) { content: '←' / 'Previous slide'; }
.carousel::scroll-button(inline-end) { content: '→' / 'Next slide'; }
}In unsupporting browsers, the carousel falls back to a scrollable, snapping strip: swipe or scroll works, but there are no dots and no prev/next buttons.
::column::scroll-marker: future variant
The CSS Overflow 5 specification includes a planned variant: ::column::scroll-marker, intended for multi-column layout carousels where the scroll targets are CSS columns rather than individual child elements. This is in the spec exploration phase and has not shipped in any browser as of 2026.
Browser Support
| Browser | First version | Notes |
|---|---|---|
| Chrome | 135 | Full support: ::scroll-marker, ::scroll-button(), :target-current, scroll-marker-group |
| Firefox | — | Not shipped; tracked as an Interop proposal, with a Mozilla standards-position issue open. No shipping timeline announced as of 2026-07 |
| Safari | — | Not shipped; tracked as an Interop proposal, with a WebKit standards-position issue open. No shipping timeline announced as of 2026-07 |
| Edge | 135 | Chromium-based; same support as Chrome |
Feature detection:
@supports (scroll-marker-group: after) {
/* CSS Carousel Primitives are supported */
}const supportsCarouselPrimitives = CSS.supports('scroll-marker-group', 'after');Production guidance: As of 2026-07, CSS Carousel Primitives are Chrome/Edge-only. MUST NOT ship to production as a sole carousel implementation. Use @supports progressive enhancement and keep a JavaScript fallback (or a static scroll strip) for Firefox and Safari users. Reassess when Firefox or Safari ships support.
Related Topics
- FEE-11100 Scroll-driven Animations: Scroll-driven Animations and CSS Carousel Primitives are both scroll-based CSS features. Combine them to animate carousel slide transitions as a function of scroll position, without JavaScript.
- FEE-11101 @starting-style:
@starting-stylecan animate carousel items entering the view for the first time. Apply@starting-styleon.carousel imgto define the from-state of the entry animation.
References
- Chrome for Developers, "Carousels with CSS," Chrome for Developers (2025). https://developer.chrome.com/blog/carousels-with-css
- W3C, "CSS Overflow Module Level 5," W3C First Public Working Draft (2024). https://www.w3.org/TR/css-overflow-5/
- MDN Web Docs, "::scroll-marker," MDN Web Docs (2025). https://developer.mozilla.org/en-US/docs/Web/CSS/::scroll-marker
- Geoff Graham, "CSS Carousels," CSS-Tricks (2025). https://css-tricks.com/css-carousels/
- Robert Flack, "Carousel (Explainer)," GitHub Pages (2025). https://flackr.github.io/carousel/
- Open UI, "Focusgroup (Explainer)," Open UI. https://open-ui.org/components/scoped-focusgroup.explainer/
- Web Platform Tests, "Interop 2026 proposal: Scroll Markers," GitHub (2025). https://github.com/web-platform-tests/interop/issues/1131