You redesign a docs page. Sticky header, clean table of contents down the side, the kind of polish that makes a demo look finished. Then someone clicks "Installation" in the TOC, and the page jumps — except the "Installation" heading is now sitting behind the header, top third clipped off, like the scroll stopped one beat too early.

It's not a bug in your heading. It's not a bug in the TOC link. The browser scrolled exactly where you told it to. You just never told it about the header.

The obvious fix that didn't quite work

The TOC links are plain anchors: <a href="#installation">. The browser handles the jump on its own — no JavaScript required, which is exactly why it feels like it shouldn't need any. So the first fix is the one that feels native to the problem: intercept the click, do the math yourself.

document.querySelectorAll('a[href^="#"]').forEach((link) => { link.addEventListener("click", (e) => { e.preventDefault(); const id = link.getAttribute("href").slice(1); const target = document.getElementById(id); const headerHeight = document.querySelector("header").offsetHeight; window.scrollTo({ top: target.getBoundingClientRect().top + window.scrollY - headerHeight - 16, behavior: "smooth", }); }); }); 

It works. Click a TOC link, the heading lands below the header, clean. Ship it, close the ticket.

Then QA files three more:

  • Deep-linking straight to yoursite.com/docs#installation — no click ever fired — still lands the heading behind the header, because the hack only runs on click.
  • The browser's native back/forward button restores the old scroll position, not yours — hitting Back after a TOC click snaps right back behind the header.
  • Mobile ships a taller header. headerHeight was read once on load; resize the window and the offset is stale until a reload.

Each of those is a separate bug with a separate fix — handle DOMContentLoaded for the deep-link case, listen for popstate, re-read offsetHeight on resize. You're not patching one bug anymore. You're reimplementing the browser's own "scroll to this element" logic, one missed case at a time, in a <script> tag.

The browser already asks "how much space do you need"

Fragment navigation, Element.scrollIntoView(), and the browser scrolling a focused element into view as you tab through the page all go through the same question: what counts as "this element is now in view"? Since 2021, every major browser has agreed on an answer CSS checks before any of them run — scroll-margin-top and its counterpart, scroll-padding-top.

Put it on the headings themselves:

h2, h3 { scroll-margin-top: 4.5rem; /* roughly the header's height, plus breathing room */ } 

That's it. No click handler, no preventDefault(), no recomputed pixel offset. Click a TOC link, hit the browser's native back button, paste a #installation link straight into the address bar — every path the browser uses to bring that heading into view now stops 4.5rem early, because the browser itself is doing the arithmetic, the same way it always has.

Per-heading vs. whole-page: pick the one that matches the bug

scroll-margin-top goes on the target — the thing being scrolled to. scroll-padding-top goes on the scroll container — usually html, or whatever element actually scrolls — and applies the same offset to every target inside it, without touching each heading individually:

html { scroll-padding-top: 4.5rem; /* one declaration, covers every #anchor on the site */ } 

If every page on the site sits under the same sticky header, scroll-padding-top on html is the one-line, whole-site fix — set it once, forget it. Reach for scroll-margin-top on specific elements instead when different targets need different offsets: a shorter mobile header, a taller "in-page alert" banner above certain sections, or a card in a horizontally-scrolling carousel that needs its own left-edge margin rather than a top one.

🎮 Try it yourself

▶️ Open the interactive playground →

Runs right in your browser — poke at it and watch the concept react live.

Stop hardcoding the header's height as a magic number

4.5rem is a guess that goes stale the day someone adds a banner to the header. Read the header's real height instead, and feed it in as a custom property:

:root { --header-h: 64px; /* kept in sync with the header's actual rendered height */ } h2, h3 { scroll-margin-top: calc(var(--header-h) + 16px); } 
const header = document.querySelector("header"); const setHeaderHeight = () => document.documentElement.style.setProperty("--header-h", `${header.offsetHeight}px`); setHeaderHeight(); new ResizeObserver(setHeaderHeight).observe(header); 

Now the only JavaScript left is measuring the header — not re-deriving the browser's entire scroll-to-element behavior. If the header grows a second row on mobile, ResizeObserver catches it and the custom property updates; scroll-margin-top reads the new value on the next scroll. The division of labor is the point: JavaScript's job shrinks to "report one number," and CSS's job — "stop scrolling here" — stays where the browser already does it for free.

Where this still needs a human

scroll-margin-top fixes where the page lands. It doesn't fix a heading that's visually ambiguous about whether it's "the current section" once it's sitting right under the header edge — that's a design question about header contrast and spacing, not a CSS-property question. And if your TOC also needs to highlight the active section as the reader scrolls, that's a separate job (usually IntersectionObserver), not something scroll-margin-top does for you. It solves exactly one problem — stopping short of the header — and it's worth not asking it to solve the other two.

🧠 Test yourself

Think it clicked? Take the 7-question quiz →

Instant feedback, a hint on every question, and an explanation for each answer — right or wrong.

The bug report wasn't "the table of contents is broken." It was "the browser doesn't know about your header" — and it turns out the browser was willing to be told, in CSS, for free, since before most of us noticed. Got a scroll offset hack sitting in a click handler somewhere? Go check what it's actually compensating for — there's a decent chance one property replaces it.

🚀 Want more like this? Every guide, playground, and quiz lives on bestpractic.org — open it and sign up free so the next one finds you.

Thanks for reading! Let's stay connected: