scroll-behavior

scroll-behavior controls scrolling triggered by navigation or CSSOM scrolling APIs. It does not turn ordinary wheel or touch scrolling into a custom animation.

Trigger smooth scrolling in a real container

The button calls scrollIntoView without an explicit behavior override. The container’s smooth rule therefore controls its movement.

<button
  type="button"
  onclick="document.getElementById('target').scrollIntoView({block: 'start'})"
>
  Scroll to target
</button>
<div
  class="viewport"
  tabindex="0"
  role="region"
  aria-label="Scrollable practice area"
>
  <div class="spacer">Scroll area begins here.</div>
  <p class="target" id="target">Target paragraph</p>
  <div class="spacer">Space after the target.</div>
</div>

.viewport {
  height: 150px;
  overflow: auto;
  border: 2px solid #94a3b8;
}
.spacer {
  height: 180px;
  background: #eff6ff;
}
.target {
  padding: 0.75rem;
  background: #bfdbfe;
  margin: 0;
}
button {
  padding: 0.75rem;
  font: inherit;
  margin-bottom: 0.5rem;
}
.viewport {
  scroll-behavior: smooth;
}
@media (prefers-reduced-motion: reduce) {
  .viewport {
    scroll-behavior: auto;
  }
}

Keep navigation instant when motion is reduced

This document enables smooth viewport navigation only when the user has not requested reduced motion. The default remains auto, which scrolls instantly.

<a href="#destination">Jump to the destination</a>
<div class="spacer">Scroll past this area.</div>
<h2 id="destination">Destination</h2>

html {
  scroll-behavior: auto;
}
@media (prefers-reduced-motion: no-preference) {
  html {
    scroll-behavior: smooth;
  }
}
.spacer {
  height: 400px;
  background: #eff6ff;
}

Values and defaults

The initial value is auto and the property is not inherited. Auto is instant; smooth uses browser-defined timing and easing. User agents may ignore the property. An explicit API behavior such as instant can override the CSS choice. ScrollIntoView is a JavaScript API, not a CSS property.

Common mistakes

Smooth does not polyfill a browser that lacks support and does not guarantee identical timing. For document scrolling, set the root html rule; a body declaration is not propagated to the viewport in the same way. Scrolling is not focus management: when navigation needs a focus change, handle that separately with care. Do not force prolonged motion for every interaction.

Learn scroll-margin, scroll-padding, and overflow.

Sources and browser support

MDN: scroll-behavior describes the syntax and links to the specification and compatibility data. Check individual values in that table when supporting older browsers.