🧲 CSS scroll-margin — Complete Tutorial

The CSS scroll-margin property controls the extra space around an element when it is scrolled into view using scroll snapping, anchor links, or JavaScript methods like scrollIntoView(). It acts like a “buffer zone” between the element and the scroll container.

>>“Use scroll-margin when a section scrolls too close to the top — it creates breathing space.”

Note

✔ Works only when an element is being scrolled **into view**
✔ Does NOT change layout—only scroll positioning
✔ Often used with scroll-snap-align, anchors, and sticky headers

📦 Syntax

scroll-margin syntax

scroll-margin: <length>;
PropertyPurpose
scroll-marginShorthand for all sides
scroll-margin-topSpace before element when scrolled
scroll-margin-rightRight-side scroll offset
scroll-margin-bottomOffset after scrolling
scroll-margin-leftLeft-side scroll offset

📌 Why Use scroll-margin?

  • Prevent anchor links from being hidden behind sticky headers
  • Improve scroll-snapping behavior
  • Add spacing without changing layout
  • Fine-tune scrollIntoView() positioning

✨ 1. Basic Example

Basic scroll-margin

section {
  scroll-margin-top: 50px;
}

Now when the section scrolls into view (via anchor or JS), it appears with 50px space above it.

✨ 2. Fix Sticky Header Anchor Problem

Sticky headers often overlap content when clicking anchor links like<a href="#contact">Contact</a>.

Offset anchor target

#contact {
  scroll-margin-top: 80px;   /* matches header height */
}

Note

This is the most common use of scroll-margin.

✨ 3. Use with scrollIntoView()

JavaScript + scroll-margin

document.querySelector('#section3')
  .scrollIntoView({ behavior: 'smooth' });

scroll-margin modifies where the target stops.

✨ 4. Scroll Snap + scroll-margin

Perfect for carousels, full-page sliders, and timelines.

Snap alignment improved with scroll-margin

.slide {
  scroll-snap-align: start;
  scroll-margin-left: 20px;
}

✨ 5. Shorthand Version

Shorthand scroll-margin

.card {
  scroll-margin: 20px 10px;
}

Same order as margin:top right bottom left

🧪 Real-World Use Cases

1️⃣ Section Navigation

Sections with breathing room

section {
  scroll-margin-top: 60px; /* header height */
}

2️⃣ Carousel or Slider

Card slider

.card {
  scroll-snap-align: center;
  scroll-margin: 0 15px;
}

3️⃣ Chat or Logs View

Message scroll

.message {
  scroll-margin-bottom: 40px;
}

⚠️ Common Mistakes

  • ❌ Expecting it to change actual spacing (it only affects scrolling)
  • ❌ Using it on non-scrollable containers
  • ❌ Forgetting scroll-margin works only when the element becomes a scroll target
  • ❌ Confusing scroll-margin with scroll-padding

Note

✔ scroll-margin adjusts the target
✔ scroll-padding adjusts the container

🔥 Summary

scroll-margin gives you fine control over how elements position themselves when brought into view. It is essential for anchor navigation, scroll snapping, and sticky header layouts.

>>“scroll-margin makes scrolling feel intentional, precise, and user-friendly.”