scrollIntoView() Hidden by a Fixed Header: Use scroll-margin-top

Choose the property at the right boundary#

scroll-padding-top describes the safe area inside a scroll container. It is a good default when the document viewport has one fixed header:

1
html {
2
  scroll-padding-block-start: var(--site-header-height);
3
}

scroll-margin-top describes extra space around the element being scrolled into view. Use it when only selected headings need an offset, or when a component owns its own target rule:

1
h2,
2
h3,
3
[id] {
4
  scroll-margin-block-start: calc(var(--site-header-height) + 1rem);
5
}

Do not blindly give the same large value to both properties. The browser can account for both the container’s scroll padding and the target’s scroll margin, so the result may leave too much empty space. Start with scroll-padding-block-start on html; add target margin only where a component needs extra breathing room.

The logical block-start forms also work when a layout changes writing mode. If the site is strictly horizontal, scroll-padding-top and scroll-margin-top are easier to search for while debugging.

Keep the JavaScript focused on behavior#

The DOM API determines which element to reveal and how it should move. CSS determines where that element may settle:

1
const link = document.querySelector('[data-open-settings]');
2
const target = document.querySelector('#settings');
3

4
link?.addEventListener('click', () => {
5
  target?.scrollIntoView({
6
    behavior: window.matchMedia('(prefers-reduced-motion: reduce)').matches
7
      ? 'auto'
8
      : 'smooth',
9
    block: 'start',
10
    inline: 'nearest',
11
  });
12
});

This keeps the reduced-motion preference in the interaction code without baking the header’s current pixel height into every event handler. It also lets normal #settings links use the same offset.

If the header height is dynamic, publish the measured value as a CSS custom property:

1
const header = document.querySelector('[data-site-header]');
2

3
if (header) {
4
  const updateHeaderOffset = () => {
5
    const height = header.getBoundingClientRect().height;
6
    document.documentElement.style.setProperty(
7
      '--site-header-height',
8
      height + 'px',
9
    );
10
  };
11

12
  updateHeaderOffset();
13
  new ResizeObserver(updateHeaderOffset).observe(header);
14
}

The observer is useful for a responsive header that changes after hydration. Keep it attached to the element that actually covers the viewport; measuring a hidden desktop navigation element produces the wrong offset.

Handle nested scrolling containers separately#

If the target is inside a panel with its own overflow: auto, setting padding on html may not affect that panel. Put the safe area on the container that scrolls:

1
.settings-panel {
2
  overflow: auto;
3
  scroll-padding-block-start: 1rem;
4
}
5

6
.settings-panel [data-scroll-target] {
7
  scroll-margin-block-start: 1rem;
8
}

Then inspect which ancestor actually moves when scrollIntoView() runs. A page-level header may cover the panel even when the panel itself has no header; in that case, reserve space in the layout or use a target-specific margin that includes the visible obstruction.

Troubleshoot the failure in order#

Check these boundaries before changing the scroll math:

1. Confirm the target exists and is an element, not a collection or a framework ref wrapper.
2. Confirm the target has a stable id and the link points to the same value.
3. Confirm the fixed or sticky header is actually covering the target after the scroll.
4. Identify the scrolling container and apply padding there.
5. Measure the header after fonts, banners, and responsive navigation have settled.
6. Test keyboard focus, direct hash navigation, reduced motion, and a short viewport.

If the console says scrollIntoView is not a function, the issue is usually that the code selected a NodeList, a null value, or a framework ref rather than an Element. scrollIntoView Is Not a Function covers that type boundary; this article assumes the method runs but the target is visually covered.

FAQ#