scroll-behavior in CSS: animated anchor scrolling without JavaScript

Clicking an anchor link like #section-2 normally makes the page jump instantly to that spot, with no transition at all. That abrupt jump long pushed developers to write JavaScript just to animate the movement. scroll-behavior solves this exact case in a single line of CSS, with no script needed.

It is a quiet but heavily used property in practice: an article's table of contents, a menu with internal anchors, a back-to-top button. It is usually applied once, on the root element, to affect every internal scroll on the page.

Definition

scroll-behavior defines whether a scroll triggered by navigation, a click on an anchor or a scroll started from JavaScript, happens instantly or with animation. Its default value, auto, matches the usual instant jump. The smooth value triggers a fluid animation entirely handled by the browser.

Syntax

html {
  scroll-behavior: smooth;
}

Applied to the html element, this single line is enough to animate every internal scroll in the document triggered by an anchor link, for instance <a href="#pricing">See pricing</a> pointing to <section id="pricing"> further down the page.

What scroll-behavior does not cover

scroll-behavior has no effect on scrolling triggered by the mouse wheel, a trackpad, or a scrollbar dragged by hand: these gestures stay instant by nature. It only applies to programmatic scrolling, whether triggered by an anchor link or a JavaScript call to scrollIntoView() or scrollTo(), provided the script passes the behavior: "smooth" option to stay consistent.

/* Smooth scrolling inside one specific container, not the whole page */
.sidebar {
  scroll-behavior: smooth;
  overflow-y: auto;
}

The property can also be set on a container that scrolls internally, like a sidebar with overflow-y: auto, and not only on the whole page.

Respecting prefers-reduced-motion

A scroll animation, however subtle, is still motion on screen. For some users, particularly those with vestibular disorders, this motion can cause real discomfort, ranging from mild annoyance to nausea. The operating system exposes a preference, prefers-reduced-motion, which CSS can read through a Media query.

html {
  scroll-behavior: smooth;
}

@media (prefers-reduced-motion: reduce) {
  html {
    scroll-behavior: auto;
  }
}

Common use case: back-to-top button

html {
  scroll-behavior: smooth;
}

With this setting applied once, a simple <a href="#top">Back to top</a> link is enough to recreate an animated back-to-top button, without writing a single line of JavaScript or manually computing the distance to travel.

A common trap: the anchor hidden under a fixed header

With a header using position: sticky or fixed positioning, an anchor reached through scroll-behavior: smooth can land exactly underneath that bar, its heading half-hidden. The scroll itself works perfectly: it is simply the landing point that ends up behind an element permanently sitting at the top of the screen.

section {
  scroll-margin-top: 5rem;
}

The scroll-margin-top property, set on the anchor's target, adds an invisible margin to the scroll's landing calculation, which is enough to bring the heading back into view below the fixed header.

FAQ

Support is very broad across modern browsers, with Safari having been the last major one to implement it. On a browser that does not understand it, the property is simply ignored and scrolling falls back to instant, with no error and no broken page.

No, scroll-behavior only offers two values, auto and smooth, with no setting for duration or easing curve at all: the speed is entirely decided by the browser and cannot be customized in CSS.

No, these are two complementary properties: scroll-snap-type handles automatically aligning to precise stopping points during a scroll, while scroll-behavior only animates the path between the starting point and the destination.