CSS scroll offsets: reveal anchors below a persistent header

When to use it

An incident report links from a table of contents to section headings. A persistent toolbar can cover the heading after a fragment jump even though the link worked. Put scroll-padding-block-start on the scrolling root or container that owns that toolbar, and use scroll-margin-block-start on a target when one section needs extra room. The sample chooses the document scrollport and a modest heading offset; nested scrollers require their own treatment. Confirm browser back navigation, keyboard focus, and direct loading of a fragment URL. Do not add a large top margin to every heading just to repair scrolling, since that changes the printed report and all normal page gaps.

html { scroll-padding-block-start: 5rem; }
.incident-report h2[id] { scroll-margin-block-start: 1rem; }

Cost and verification

These offsets are inexpensive, but stale values can hide content again when the toolbar changes height at narrow widths or high zoom. Prefer a sizing token tied to the actual toolbar design and test with wrapped navigation. A nested overflow container may have a different scrollport from the document. Smooth scrolling is optional and must respect reduced-motion preferences if enabled elsewhere. Keep target headings visible and focusable by the navigation behavior; a visually correct offset does not repair a missing fragment ID or misleading link label.

Common Mistakes

• Do not place the offset on the wrong scroll container.
• Do not use ordinary margins to fix only fragment scrolling.
• Do not assume the header height is fixed under zoom or translation.

Connected lessons

• CSS Property Decisions
• CSS scroll snap: align cards without trapping the reader
• CSS positioning: keep sticky controls inside their scroll boundary
• HTML anchors: use href for navigation and stable fragment targets

Further rendering decisions

• CSS scroll-behavior: make smooth jumps optional

Further interaction details

• CSS :target: confirm the section reached by a fragment