Scroll Marker Group

What Scroll Marker Group Does

The scroll-marker-group CSS property controls whether a scroll container generates a ::scroll-marker-group pseudo-element, which serves as a container for scroll markers associated with the scrollable content. When you apply this property to a scroll container, the browser automatically creates a dedicated area where scroll markers are displayed and organized.

These markers act as navigation anchors, allowing users to click and jump to specific scroll targets within the container. The feature is part of the CSS Overflow Module Level 5 specification, representing the web platform's continued evolution toward more interactive, CSS-driven interfaces.

For modern web development teams, scroll marker group addresses a common pain point: creating accessible navigation controls for scrollable content. Traditionally, building features like carousel pagination or section navigation required JavaScript for state management, click handling, and keyboard accessibility. Scroll markers eliminate this complexity entirely, letting you declare what you want and letting the browser handle the implementation. This means fewer lines of code, fewer opportunities for bugs, and faster performance since the browser's native scroll handling is already highly optimized.

Key Benefits

• JavaScript-free navigation - Create carousel and tab interfaces using only CSS, reducing bundle size and eliminating state synchronization issues
• Built-in accessibility - Keyboard navigation and screen reader support come automatically, following WAI-ARIA patterns without requiring manual implementation
• Progressive enhancement - Works seamlessly with scroll-snap and other modern CSS features, providing an enhanced experience in supporting browsers while maintaining full functionality elsewhere
• Declarative approach - Focus on what you want to achieve, not how to implement it--the browser handles interaction mechanics, state changes, and scroll animation

Beyond these core benefits, scroll markers promote consistency across your codebase. When multiple components use the same CSS-based navigation pattern, users develop familiarity with the interaction model, reducing the learning curve for new features. The browser-managed state also eliminates common bugs like markers showing the wrong active state or becoming desynchronized from the scroll position.

How Scroll Markers Work

The ::scroll-marker Pseudo-Element

The ::scroll-marker pseudo-element represents an individual scroll marker associated with a scroll target. Each scroll target within a scroll container can have a ::scroll-marker that appears within the ::scroll-marker-group pseudo-element. When users interact with these markers--clicking them with a pointer or activating through keyboard input--the browser scrolls the corresponding target into view using scroll-snapping behavior.

Individual ::scroll-marker pseudo-elements can be styled to reflect their state, including whether their associated target is currently visible. The :target-current pseudoclass specifically targets the scroll marker whose corresponding scroll target is currently in view, enabling patterns like highlighting the current page in a pagination control or emphasizing the visible section in a carousel.

.carousel-item::scroll-marker:target-current {
 background: #333;
 transform: scale(1.2);
}

Scroll Target Groups

Scroll targets are elements within a scroll container that have associated scroll markers. For an element to become a scroll target, it must either have an ID that is referenced by an anchor link within the scroll container, or it must explicitly opt-in to being a scroll target using the scroll-target property. This flexibility allows you to control which elements receive markers, enabling scenarios where not every section needs a navigation marker.

The scroll-target property provides explicit control over which elements generate scroll markers. By default, elements with IDs that are linked to from within the same scroll container become scroll targets automatically. However, scroll-target allows you to override this behavior--either enabling markers for elements without IDs or disabling markers for elements that would otherwise qualify. This granular control is useful when you want to group related content under a single marker or when automatic detection would create too many navigation points. For more details on scroll-target, see our guide on Scroll Target Group.

/* Explicitly enable scroll target */
.section-no-id {
 scroll-target: auto;
}

/* Explicitly disable scroll target */
.ignore-target {
 scroll-target: none;
}

Target Optical Center

Understanding Target Positioning

When a user clicks a scroll marker, the browser determines where to scroll the target element within the scroll container. The target optical center concept refers to ensuring that meaningful content appears where users expect it--typically centered or prominently visible. This becomes especially important when scroll targets have varying heights or when the scroll container has specific aspect ratios that affect visibility.

Scroll-snap's scroll-snap-align property provides the primary mechanism for controlling target positioning:

• start - Aligns the target's start edge with the scroll container's start edge. Ideal for section-based navigation where headings should appear at the top.
• end - Aligns the target's end edge with the scroll container's end edge. Useful when content should anchor to the bottom of the view.
• center - Centers the target within the scroll container. The most common choice for carousel slides and equal-height content sections.

Best Practices for Target Positioning

• For carousels, snap each slide to be fully visible using center alignment to maximize content prominence
• For long-form content sections, position headings near the top using start alignment to maintain clear context
• Use scroll-padding on the container for fine-tuned control around fixed headers or navigation bars
• Test edge cases like first and last targets, which may snap differently at container boundaries

.carousel {
 scroll-snap-type: x mandatory;
 scroll-padding: 20px; /* Breathing room around edges */
}

.carousel-item {
 scroll-snap-align: center; /* Center slides in view */
}

Practical Implementation: Carousel Example

Building a carousel with scroll markers demonstrates the feature's practical application. The HTML structure consists of a scroll container with multiple child elements representing slides, and scroll markers are automatically generated for each slide. Here's a complete example:

<div class="carousel" role="region" aria-label="Product Gallery">
 <div class="carousel-item" id="slide-1">
 <img src="slide1.jpg" alt="Product view 1">
 </div>
 <div class="carousel-item" id="slide-2">
 <img src="slide2.jpg" alt="Product view 2">
 </div>
 <div class="carousel-item" id="slide-3">
 <img src="slide3.jpg" alt="Product view 3">
 </div>
 <div class="carousel-item" id="slide-4">
 <img src="slide4.jpg" alt="Product view 4">
 </div>
</div>

How It Works Together

The carousel container enables horizontal scrolling with overflow-x: auto and establishes snapping behavior with scroll-snap-type: x mandatory. Each item takes full width with flex: 0 0 100% and snaps to the center of the container. When scroll-marker-group: after is applied, the browser generates a ::scroll-marker-group pseudo-element containing markers for each carousel item.

Styling the marker group uses flexbox to center the pagination dots, while individual markers are styled as circles with border-radius: 50%. The :target-current pseudoclass provides visual feedback by changing the active marker's background color, giving users clear indication of their current position in the slideshow.

The implementation requires no JavaScript for navigation functionality--clicking markers, keyboard navigation, and scroll-snapping all work natively. This approach reduces bundle size, eliminates client-side state management code, and provides consistent behavior across devices and input methods. For more advanced carousel techniques, explore our CSS Scroll Snap guide.

Accessibility Considerations

Keyboard Navigation

Scroll markers are designed with accessibility as a core principle, providing keyboard-accessible navigation out of the box:

• Tab order respects scroll-marker-group value - Markers placed at beginning or end of sequence based on before or after
• Arrow key navigation - Users can navigate through markers using keyboard, moving between sections without scrolling
• Activation - Enter or Space activates a marker, scrolling to the associated target

Screen Reader Support

• Automatic labeling - Browser generates accessible names from target content, including heading text and data attributes
• ARIA integration - Works with existing accessibility tree, no additional ARIA attributes required
• No manual ARIA needed - Built-in support eliminates custom workarounds and potential accessibility mistakes

Testing Accessibility

When implementing scroll markers, test with actual assistive technologies:

1. Keyboard-only testing - Navigate using only Tab, Enter, and arrow keys
2. Screen reader testing - Use NVDA, VoiceOver, or JAWS to verify announcements
3. Focus visible testing - Ensure focus states are clearly visible on all markers
4. Reduced motion testing - Verify behavior when prefers-reduced-motion is enabled

@media (prefers-reduced-motion: reduce) {
 .carousel {
 scroll-behavior: auto;
 }
 
 .carousel::scroll-marker-group {
 transition: none;
 }
}

Progressive Enhancement

A key advantage of scroll markers is their progressive enhancement nature. In browsers that don't support the feature, the markers simply don't appear, leaving the scrollable content fully functional through traditional scrolling. The core content remains accessible and usable, with scroll markers serving as an enhancement for browsers that support them.

Best Practices

Design Guidelines

1. Keep markers visually distinct but not distracting - Simple shapes in neutral colors work well, with more prominent styling reserved for the active state via :target-current
2. Provide clear active state feedback - Use :target-current to highlight current position with color, size, or opacity changes
3. Ensure adequate spacing - Prevent accidental clicks, especially on touch devices. Aim for 44px minimum touch targets
4. Consider placement carefully - Fixed positioning for persistent navigation, inline for content-integrated markers like carousel pagination

Common Pitfalls to Avoid

• Overloading with too many markers - If you have more than 7-8 scroll targets, consider grouping related sections or using a different navigation pattern
• Ignoring the before/after choice - The placement affects tab order, which impacts keyboard users. Match visual placement to logical navigation sequence
• Forgetting scroll-padding - Without proper padding, content may snap behind fixed headers, creating poor user experience
• Neglecting focus styles - Ensure keyboard users can see which marker has focus

Performance Considerations

• Pseudo-element implementation - No DOM nodes added, minimal layout impact compared to JavaScript-based navigation
• Native scroll handling - Browser optimizes scroll performance, avoiding janky animations from JavaScript scroll manipulation
• Test on target devices - Complex configurations with multiple scroll features may affect scroll performance on lower-powered devices

Feature Detection Pattern

@supports selector(::scroll-marker-group) {
 .scroll-container {
 scroll-marker-group: after;
 }
}

/* Fallback for older browsers - consider a simple indicator */
@supports not selector(::scroll-marker-group) {
 .scroll-container {
 /* Alternative: CSS scroll-snap still works */
 scroll-snap-type: x mandatory;
 }
}

Sources

1. MDN Web Docs - scroll-marker-group
2. CSS-Tricks - ::scroll-marker-group
3. MDN Web Docs - ::scroll-marker
4. WebKit Blog - Safari 26 Features