CSS scroll-margin Property

What You’ll Learn

The scroll-margin property adds breathing room around elements when they become scroll targets. It is especially helpful for anchor links and scrollIntoView() when fixed headers would otherwise hide the destination.

Introduction

The scroll-margin property in CSS allows developers to define the margin around an element when it is scrolled into view.

This property is particularly useful for ensuring that elements are not flush against the edge of the viewport when using functions like scrollIntoView(). By adjusting the scroll margin, you can create a more visually pleasing and user-friendly scrolling experience.

Definition and Usage

Apply scroll-margin to the element that will be scrolled to — such as a section with an id, a heading anchor, or a card targeted by JavaScript.

Unlike regular margin, scroll-margin does not change layout spacing between siblings. It only affects the scroll snap area and where the browser positions the element after navigation.

📝 Syntax

The scroll-margin property can be applied to any element, and it accepts length values for specifying the margin around the element when it is scrolled into view.

element {
  scroll-margin: value;
}

Basic Example

.target {
  scroll-margin-top: 50px;
}

Longhand Properties

• scroll-margin-top, scroll-margin-right, scroll-margin-bottom, scroll-margin-left
• scroll-margin-block, scroll-margin-inline
• scroll-margin-block-start, scroll-margin-block-end, scroll-margin-inline-start, scroll-margin-inline-end

Syntax Rules

• One to four values work like regular margin shorthand.
• Length units such as px, rem, and em are common.
• Percentages are relative to the element’s own dimensions.
• Set the offset on the target element, not on the scroll container.

🎯 Default Value

The default value of the scroll-margin property is 0, meaning no additional margin is applied.

💎 Property Values

When to Use scroll-margin

scroll-margin solves common scroll-position problems:

• Sticky navigation — Keep section headings visible below a fixed or sticky header.
• Anchor link pages — Improve table-of-contents jumps on docs and landing pages.
• JavaScript scrolling — Offset targets when calling element.scrollIntoView().
• Scroll snapping — Fine-tune where snapped items land inside a scroll container.

If you need to inset the scrollable viewport itself, use scroll-padding on the container instead.

Examples Gallery

Start with the reference scroll-margin-top example, fix sticky-header overlap, try shorthand values, and use rem units with a fixed banner.

<style>
  section {
    height: 100vh;
    border: 1px solid black;
  }

  .target {
    scroll-margin-top: 50px;
  }
</style>

<button onclick="document.querySelector('.target').scrollIntoView({ behavior: 'smooth' })">
  Scroll to Section 3
</button>
<section class="target">Section 3</section>

section[id] {
  scroll-margin-top: 4rem;
}

#panel-b {
  scroll-margin: 24px 12px;
}

#chapter-2 {
  scroll-margin-top: 3.5rem;
}

scroll-margin with scroll-behavior

Smooth scrolling from scroll-behavior feels better when targets land in a comfortable position. Use both together on documentation pages with sticky navigation.

Remember: scroll-margin goes on the target element; scroll-padding goes on the scroll container when you need viewport insets.

html {
  scroll-behavior: smooth;
}

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

💡 Best Practices