CSS scroll-behavior Property

The CSS scroll-behavior property defines whether a scroll triggered by the navigation or by a script (a "scrolling box" jumping to an anchor or to a coordinate) should be smooth (animated) or instant (a single jump). By default it is auto, which means an abrupt jump.

This page covers what the property does, where you must declare it, the difference between its values, common gotchas, and how it relates to JavaScript scrolling APIs.

When would I use it?

The most common use case is in-page navigation. When a link points to a fragment such as <a href="#section">, the browser normally jumps instantly to the target. Setting scroll-behavior: smooth on the scroll container turns that jump into a pleasant animated scroll — without a single line of JavaScript.

html {
  scroll-behavior: smooth;
}

Where to declare it

Two rules trip people up:

It only affects programmatic and navigation-triggered scrolls — clicking an anchor, calling element.scrollIntoView(), window.scrollTo(), etc. It has no effect on scrolls the user performs with the wheel, trackpad, or scrollbar.
For viewport scrolling, set it on html, not body. The value declared on the body element does not propagate to the viewport, so it would be ignored. Declare it on the html element (the root scrolling box). For any other scrollable container, declare it on that container itself.

User agents are allowed to ignore this property, and it will be skipped for users who request reduced motion (see Accessibility below).

Initial Value	auto
Applies to	Scrolling boxes.
Inherited	No.
Animatable	No.
Version	CSSOM View Module (Working Draft)
DOM Syntax	object.style.scrollBehavior = "smooth";

Syntax

CSS scroll-behavior syntax

scroll-behavior: auto | smooth | initial | inherit;

Example of the scroll-behavior property with the "auto" value:

CSS scroll-behavior code example

<!DOCTYPE html>
<html>
  <head>
    <title>Title of the document</title>
    <style>
      html {
        scroll-behavior: auto;
      }
      #element1 {
        height: 600px;
        background-color: #ccc;
      }
      #element2 {
        height: 600px;
        background-color: #8ebf42;
      }
    </style>
  </head>
  <body>
    <h2>Scroll-behavior property example</h2>
    <div class="main" id="element1">
      <h2>Element 1</h2>
      <a href="#element2">Click to scroll to Element 2</a>
    </div>
    <div class="main" id="element2">
      <h2>Element 2</h2>
      <a href="#element1">Click to scroll to Element 1</a>
    </div>
  </body>
</html>

Try it Yourself »

Example of the scroll-behavior property with the "smooth" value:

CSS scroll-behavior with smooth value, example

<!DOCTYPE html>
<html>
  <head>
    <title>Title of the document</title>
    <style>
      html {
        scroll-behavior: smooth;
      }
      #element1 {
        height: 600px;
        background-color: #ccc;
      }
      #element2 {
        height: 600px;
        background-color: #8ebf42;
      }
    </style>
  </head>
  <body>
    <h2>Scroll-behavior property example</h2>
    <div class="main" id="element1">
      <h2>Element 1</h2>
      <a href="#element2">Click to scroll to Element 2</a>
    </div>
    <div class="main" id="element2">
      <h2>Element 2</h2>
      <a href="#element1">Click to scroll to Element 1</a>
    </div>
  </body>
</html>

Try it Yourself »

With smooth, clicking either link animates the page between the two blocks instead of jumping instantly. Only the scroll-behavior value differs from the previous example.

Values

Value	Description
auto	Default. The scroll happens in a single instant jump, with no animation.
smooth	The scroll is animated smoothly between the start and end positions.
initial	Sets the property to its default value (`auto`).
inherit	Inherits the value from the parent element.

Smoothing a specific container

scroll-behavior is not limited to the page. Declare it on any element that has its own scrollbar (an overflow: auto or overflow: scroll box) and programmatic scrolls inside that container animate too. See overflow for how scrollable boxes are created.

.panel {
  height: 300px;
  overflow-y: auto;
  scroll-behavior: smooth;
}

// Smoothly scrolls .panel to its bottom because the
// container has scroll-behavior: smooth.
const panel = document.querySelector('.panel');
panel.scrollTop = panel.scrollHeight;

Relationship to JavaScript scroll APIs

scroll-behavior is the CSS way to set the default animation for a scroll container. The scroll APIs can also request smoothing per call with a behavior option, which overrides the CSS value for that single call:

// One-off smooth scroll, regardless of the CSS scroll-behavior value.
element.scrollIntoView({ behavior: 'smooth' });
window.scrollTo({ top: 0, behavior: 'smooth' });

Use the CSS property when you want every navigation/anchor jump in a container to be smooth; use the JS option for a single, ad-hoc scroll.

Accessibility

Smooth scrolling can cause discomfort for users who are sensitive to motion. Respect the prefers-reduced-motion media query so the animation is disabled when the user has asked the system to reduce motion:

html {
  scroll-behavior: smooth;
}

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

overflow — create the scrollable boxes that scroll-behavior animates.
scrollbar — style the scrollbar of those boxes.
offset-anchor — control the anchor point used during transforms.
HTML links — the href="#id" anchors that trigger smooth scrolling.

Practice

What does the CSS property 'scroll-behavior' control in a webpage?

It controls the text color on a webpage.It controls the background color of a webpage.It controls whether a webpage can be scrolled or not.It controls the scrolling mechanism of the page i.e., whether the page scrolling transitions are smooth.