← blog
CSSNovember 21, 2026 · 5 min read

Your Sticky Header Is Hiding Anchor Links. scroll-margin-top Fixes It.

Clicking a table-of-contents link lands the heading right behind your sticky nav, half-hidden. The fix isn't a JavaScript scroll offset — it's one CSS property the browser already checks before it scrolls.

Parsa Jiravand · Frontend engineer · building bestpractic
Your Sticky Header Is Hiding Anchor Links. `scroll-margin-top` Fixes It.

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 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.

JavaScript
1
2
3
4
5
6
7
8
9
10
11
12
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.

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:

CSS
1
2
3
4
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.

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:

CSS
1
2
3
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.

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

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:

CSS
1
2
3
4
5
6
7
8
:root { --header-h: 64px; /* kept in sync with the header's actual rendered height */ } h2, h3 { scroll-margin-top: calc(var(--header-h) + 16px); }
JavaScript
1
2
3
4
5
6
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.

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.

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:

Keep reading

One post a day, in your inbox

Each one with a runnable playground and a quiz. No pitch, no digest, unsubscribe in one click.

0 comments

Sign in to join the discussion, like comments, and save articles for later.