behavior variant · Menus and navigation
Scrollspy
Scroll-linked in-page navigation that updates one current section link as the reader moves through matching heading targets.
Decisive boundary
Scrollspy reflects document position; Tabs activate one panel and should not be used for a page whose sections all remain in the document.
Definition and intent
What is a Scrollspy UI pattern?
Use the behavior, not the silhouette
Scroll-linked in-page navigation that updates one current section link as the reader moves through matching heading targets. The term is used here as a behavior variant that normally modifies another control rather than defining a complete component by itself. That distinction prevents a visual resemblance from silently deciding focus, keyboard, modality, or dismissal behavior.
Help readers understand their position in a long page and jump directly to another section. A good implementation preserves that job while making the trigger, open state, close path, and responsive behavior observable to users.
Know when the label is wrong
The fastest way to identify a pattern is often to reject the nearest alternative. For Scrollspy, the boundary is: Scrollspy reflects document position; Tabs activate one panel and should not be used for a page whose sections all remain in the document.
Do not implement it as Tabs for mutually exclusive panels and Sticky positioning alone when no active section state is updated. If those requirements describe the real task better, use the related pattern page or the full Menus and navigation comparison before writing code.
Decision process
Decide before choosing a component
Record these requirements in plain language. A library component name is not a substitute for the contract.
Confirm the user job
Help readers understand their position in a long page and jump directly to another section.
Define opening and closing
Scrolling or following a same-page fragment link changes the current section. Not dismissed; the current indicator moves as another section becomes active.
Specify access behavior
Normal fragment links remain focusable; scroll observation does not move keyboard focus. Links work as ordinary same-document navigation, and programmatic scrolling preserves visible focus and reduced-motion preferences.
Reject the near miss
Tabs for mutually exclusive panels and Sticky positioning alone when no active section state is updated.
Behavior contract
What must survive the build
- trigger
- Scrolling or following a same-page fragment link changes the current section.
- dismissal
- Not dismissed; the current indicator moves as another section becomes active.
- modality
- Non-modal navigation behavior.
- focus
- Normal fragment links remain focusable; scroll observation does not move keyboard focus.
- keyboard
- Links work as ordinary same-document navigation, and programmatic scrolling preserves visible focus and reduced-motion preferences.
- interactive
- Contains links to real heading IDs; the active state reflects location rather than selecting a hidden panel.
- persistence
- Remains available while reading the document and tracks one current section.
- placement
- Often in a sticky on-this-page rail beside or above long content.
- mobile
- May collapse into a compact contents control while preserving real fragment links and the current-section label.
Failure modes
Common wrong builds
- Marking several links current at once.
- Using links whose fragment IDs do not exist.
- Moving focus on every scroll update.
Observable checks
Verify the result
- Every navigation link resolves to a real section ID.
- Exactly one visible link is marked current.
- Scrolling does not steal focus.
- Sticky-header offset is included in activation and fragment positioning.
- The mobile version preserves usable in-page navigation.
Coding-agent handoff
Implementation brief template
Pattern: Scrollspy Purpose: Help readers understand their position in a long page and jump directly to another section. Trigger: Scrolling or following a same-page fragment link changes the current section. Dismissal behavior: Not dismissed; the current indicator moves as another section becomes active. Modality: Non-modal navigation behavior. Focus behavior: Normal fragment links remain focusable; scroll observation does not move keyboard focus. Keyboard behavior: Links work as ordinary same-document navigation, and programmatic scrolling preserves visible focus and reduced-motion preferences. Interactive content: Contains links to real heading IDs; the active state reflects location rather than selecting a hidden panel. Placement: Often in a sticky on-this-page rail beside or above long content. Mobile behavior: May collapse into a compact contents control while preserving real fragment links and the current-section label. Do not implement as: Tabs for mutually exclusive panels and Sticky positioning alone when no active section state is updated. Acceptance checks: - Every navigation link resolves to a real section ID. - Exactly one visible link is marked current. - Scrolling does not steal focus. - Sticky-header offset is included in activation and fragment positioning. - The mobile version preserves usable in-page navigation.
Claim-level references
Sources, not a confidence score
Frequently asked questions
Scrollspy UI pattern questions
Direct answers based on the reviewed behavior contract above.
What is a Scrollspy in web UI?
Scroll-linked in-page navigation that updates one current section link as the reader moves through matching heading targets. In this reference set it is a behavior variant that normally modifies another control rather than defining a complete component by itself.
When should I use a Scrollspy?
Help readers understand their position in a long page and jump directly to another section. The decisive boundary to confirm is this: Scrollspy reflects document position; Tabs activate one panel and should not be used for a page whose sections all remain in the document.
What keyboard and focus behavior does a Scrollspy need?
Links work as ordinary same-document navigation, and programmatic scrolling preserves visible focus and reduced-motion preferences. Normal fragment links remain focusable; scroll observation does not move keyboard focus. These statements describe the reviewed expectation, but the final implementation still needs testing in the component library and browser you ship.
How should a Scrollspy behave on mobile?
May collapse into a compact contents control while preserving real fragment links and the current-section label. Its modality is a separate requirement: Non-modal navigation behavior.
How do I verify a Scrollspy implementation?
Start with observable checks: Every navigation link resolves to a real section ID. Exactly one visible link is marked current. Scrolling does not steal focus. Then verify the remaining checks and compare the result with the linked source guidance.