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.

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.
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 runson 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.
headerHeightwas 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:
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:
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:
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.
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:
- ⭐ GitHub — follow me and star the projects: github.com/parsajiravand
- 💬 Discord — join the frontend best-practices community: discord.gg/d9KRhuAwQ
- 📸 Instagram — frontend best practices, daily: @bestpractice___
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.