Scroll-behavior controls whether scrolling initiated by navigation or scrolling APIs moves instantly or smoothly within a scroll container. It does not govern every user scroll action.
Make this comfortable
CSS scroll-behavior: make smooth jumps optional
When to use it
A long case report has links to numbered sections. Smooth fragment jumps can help some readers track the move, but others prefer immediate positioning or reduced motion. Apply the rule to the document scrollport and override it under the reduced-motion preference. The sample also reserves room for a persistent toolbar. Test direct fragment URLs, back navigation, a click from the bottom of the report, and keyboard focus after the jump. Do not make the animation so slow that the target feels unresponsive. The document's heading IDs and link labels must work when CSS is off; smoothness is presentation, not navigation logic. Nested scrolling panels may need their own behavior and offset rules.
html { scroll-behavior: smooth; scroll-padding-block-start: 5rem; }
@media (prefers-reduced-motion: reduce) { html { scroll-behavior: auto; } }Cost and verification
A long animated scroll can require repeated rendering frames and may disorient readers when the distance is large. Measure responsiveness on realistic reports, and keep the default jump if smooth motion adds no value. Browser behavior and user settings can override the request. Scroll-padding must match the actual toolbar height across zoom and responsive layouts; a smooth move to a hidden target is still a broken result. Do not use JavaScript animation just to replace this small CSS behavior unless the task requires a control CSS cannot express.
Common Mistakes
- Do not force motion on users who request less of it.
- Do not assume scroll-behavior changes manual wheel or touch scrolling.
- Do not animate to a heading that remains hidden behind a toolbar.
Connected lessons
css
reference
web