CSS scroll-behavior Property

What You’ll Learn

The scroll-behavior property controls whether scrolling is instant or animated. With one line of CSS you can make anchor links and in-page navigation feel smoother and more polished.

Introduction

The scroll-behavior property in CSS is used to control the scrolling behavior for a webpage.

This property specifies whether to use smooth scrolling or instant scrolling when a user navigates through internal links within a document or when a script calls for scrolling. Smooth scrolling provides a visually appealing and user-friendly experience, especially for single-page applications and websites with long content.

Definition and Usage

scroll-behavior applies to scroll containers — most commonly the root html element for the whole page, or any element with overflow: auto or overflow: scroll.

When set to smooth, clicking an anchor link such as <a href="#section"> scrolls gradually to the target instead of jumping instantly.

📝 Syntax

The syntax for the scroll-behavior property is simple. It can be applied to the html element to affect the entire document, or to any scrollable container.

element {
  scroll-behavior: auto | smooth;
}

Basic Example

html {
  scroll-behavior: smooth;
}

Syntax Rules

• Only two keyword values are valid: auto and smooth.
• Apply to html for document-level scrolling.
• Apply to a scroll container for scrolling inside that element.
• Works with anchor links, focus moves, and many programmatic scroll APIs.
• Does not expose custom duration or easing in pure CSS.

🎯 Default Value

The default value of the scroll-behavior property is auto, which provides an instant scrolling effect.

💎 Property Values

When to Use scroll-behavior

scroll-behavior is the right tool when in-page navigation should feel gentler:

• Anchor navigation — Smoothly scroll between sections linked with #id hashes.
• Back-to-top links — Provide a softer return to the page header.
• Scrollable panels — Improve UX inside sidebars, modals, or tab panels.
• Documentation pages — Make long single-page layouts feel more polished.

Avoid overusing smooth scrolling where users need to jump quickly, and always respect prefers-reduced-motion.

Examples Gallery

Start with the reference smooth-scrolling page, compare instant auto behavior, smooth-scroll inside a container, and add a back-to-top link.

<style>
  html {
    scroll-behavior: smooth;
  }
  section {
    height: 100vh;
    padding: 20px;
  }
</style>

<nav>
  <a href="#section1">Section 1</a>
  <a href="#section2">Section 2</a>
</nav>
<section id="section1">Section 1</section>
<section id="section2">Section 2</section>

html {
  scroll-behavior: auto;
}

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

<style>
  html { scroll-behavior: smooth; }
</style>

<header id="top">...</header>
<a href="#top">Back to top</a>

scroll-behavior with scroll-margin

Smooth scrolling looks best when the destination is fully visible. Fixed headers often cover linked sections. Use scroll-margin on targets so they stop below sticky navigation.

Also see overflow for creating scroll containers and position: sticky for persistent nav bars.

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

💡 Best Practices

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