CSS scroll-behavior Property

Description

The scroll-behavior property controls how a scroll container responds when a scrolling action is initiated: it determines whether the change in scroll position happens instantly or is animated over time. This affects both viewport scrolling (for example when navigating to an in-page anchor) and scrolling of elements that are able to overflow. The property sets a default behavior for the container so that user navigation and many programmatic scroll invocations will follow the chosen behavior unless explicitly overridden.

When a script requests a scroll (via DOM scrolling methods), many user agents will honor the container’s configured behavior unless the script supplies an explicit instruction. Likewise, following anchor links or similar navigation events will typically use the container’s scrolling behavior. That means the property interacts closely with how focus is moved and how content comes into view, so it’s often used together with layout-related properties to ensure elements land in predictable positions after scroll operations — for example scroll-margin can be used to offset the final visible position so target content doesn’t sit flush against an edge.

Accessibility and user preferences should be considered when using animated scrolling. Users who prefer reduced motion may expect or require instant changes rather than animated transitions; many browsers and assistive settings will override or ignore animated scroll behavior when a user has indicated a reduced-motion preference, so you should not rely on animated scrolling as the only way of indicating navigation. Pairing scroll behavior with focus management and semantics (so keyboard and assistive tech users get a clear navigation experience) is important — also consider how it interacts with layout properties such as overflow, because if an element is not actually scrollable the property has no effect.

From an implementation and performance perspective, animated scrolling is generally handled on compositor threads in modern browsers to avoid blocking the main thread and to produce smooth motion; however, complex repaint or layout work triggered during a scroll can still cause jank. Use animated scrolling judiciously — it can improve perceived continuity for in-page navigation, but overuse (for many simultaneous large scrollable regions or heavy DOM updates during scrolling) can degrade performance. Finally, be aware of interactions with scrolling behaviors like snapping: containers that employ scroll-snapping via scroll-snap-type may combine snapping logic with the chosen scroll animation, so test to ensure the result matches your expected UX.

Definition

Initial value: auto
Applies to: scrolling boxes
Inherited: no
Computed value: as specified
Animatable: no
JavaScript syntax: object.style.scrollBehavior

Interactive Demo

scroll-behavior: auto;

scroll-behavior: smooth;

Scroll to: A B C

A

B

C

Syntax

scroll-behavior: auto | smooth

Values

autoThe scrolling box scrolls instantly.
smoothThe scrolling box scrolls in a smooth fashion using a user-agent-defined easing function over a user-agent-defined period of time. User agents should follow platform conventions, if any.

Example

HTML

<body>

  <nav class="top-nav">

    <a href="#section1">Section 1</a>

    <a href="#section2">Section 2</a>

    <a href="#section3">Section 3</a>

    <a href="#top">Top</a>

  </nav>



  <main id="top">

    <header class="hero">

      <h1>Smooth Scroll with CSS</h1>

      <p>Click the links in the fixed navigation to jump between sections. The browser will animate the scroll.</p>

    </header>



    <section id="section1" class="panel">

      <h2>Section 1</h2>

      <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer posuere, justo non dictum porta, nunc nibh dictum arcu, nec faucibus turpis nunc nec urna.</p>

      <p>Phasellus vitae lacus a risus dictum feugiat. Curabitur sit amet mi id lorem gravida aliquet.</p>

    </section>



    <section id="section2" class="panel">

      <h2>Section 2</h2>

      <p>Nullam vel nibh sit amet quam tristique tincidunt. Mauris vitae sem non nisl facilisis gravida.</p>

      <p>Aliquam erat volutpat. Suspendisse potenti. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.</p>

    </section>



    <section id="section3" class="panel">

      <h2>Section 3</h2>

      <p>Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium.</p>

      <p>Neque porro quisquam est qui dolorem ipsum quia dolor sit amet, consectetur, adipisci velit.</p>

    </section>



    <footer class="footer">

      <p>End of demo  -  <a href="#top">Back to top</a></p>

    </footer>

  </main>

</body>

CSS

:root {
  --accent: #0b5fff;
  --bg: #f7f9fc;
  --card: #ffffff;
}

/* Enable smooth scrolling for anchor links */
html {
  scroll-behavior: smooth;
}

body {
  margin: 0;
  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
  background: var(--bg);
  color: #0b1a2b;
}

.top-nav {
  position: fixed;
  top: 0;
  left: 0;
  right: 0;
  display: flex;
  gap: 1rem;
  padding: 0.75rem 1rem;
  background: rgba(255, 255, 255, 0.9);
  backdrop-filter: blur(6px);
  box-shadow: 0 2px 10px rgba(0, 0, 0, 0.06);
  z-index: 1000;
}

.top-nav a {
  color: var(--accent);
  text-decoration: none;
  font-weight: 600;
}

.hero {
  padding: 100px 1rem 40px;
  text-align: center;
}

/* Ensure anchored sections are offset below the fixed nav */
.panel {
  padding: 80px 1rem;
  min-height: 70vh;
  background: var(--card);
  border-top: 1px solid rgba(11, 95, 255, 0.06);
  scroll-margin-top: 72px; /* offset for fixed nav when jumping to anchors */
}

.panel:nth-of-type(even) {
  background: linear-gradient(180deg, #ffffff 0%, #f6f9ff 100%);
}

h1 {
  margin: 0 0 0.5rem;
  font-size: clamp(1.5rem, 3vw, 2.25rem);
}

h2 {
  margin-top: 0;
  font-size: 1.5rem;
  color: #08306f;
}

p {
  max-width: 60ch;
  margin: 0.5rem auto;
}

.footer {
  padding: 40px 1rem;
  text-align: center;
  color: #667;
}

/* Small hover effect for links */
.top-nav a:hover,
.footer a:hover {
  text-decoration: underline;
}

Result

Editor

Browser Support

The following information will show you the current browser support for the CSS scroll-behavior property. Hover over a browser icon to see the version that first introduced support for this CSS property.