How do I keep CSS scroll snap targets below a fixed header with scroll-padding?
Keep a snapped section from landing under a fixed header by reserving space on the scroll container with scroll-padding, without changing the child snap alignment or the snap strictness.
A scroll snap container can land on the right section and still make the result unusable if a fixed header covers the heading. The bug is subtle because the snap itself succeeded: the browser chose a valid snap point, and the section aligned exactly as designed. What failed was the visible space left for that target.
The repair is usually not in the child element. It is on the scroll container, where `scroll-padding` changes the browser's optimal viewing region and gives the snapped content room to appear below the header. This article uses a minimal fixture to show the overlap first, then the same snap behavior with the heading visible again.
The snap is correct, but the header still wins the overlap
A scroll snap layout can be technically correct and still feel broken. The container may settle on the intended section, the child may have the expected `scroll-snap-align`, and the scroll position may even land exactly where the browser chose a snap point. None of that prevents a fixed header from covering the section title after the snap finishes. The browser has done the snapping work you asked for; the layout has simply reserved no room for the overlaying header.
That distinction matters because the fix is easy to aim at the wrong layer. If the header is fixed outside the scroll container, the child content is not broken. The scroller is. The optimal viewing region for the container needs an inset large enough to account for the fixed header, or the snapped target will appear underneath it. Changing the child alone does not teach the container about the header's occupied space.
The smallest useful question is not whether snapping works. It is whether the snapped target is visible after snapping completes. This article uses a controlled fixture with a single-axis snap container, a sticky-looking fixed header, and repeated sections so the overlap is easy to reproduce and verify.
export function snapFixture({ scrollPadding = false } = {}) {
const paddingRule = scrollPadding ? 'scroll-padding-top: 50px;' : '';
return `<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<style>
* { box-sizing: border-box; }
html, body { margin: 0; height: 100%; overflow: hidden; }
#scroller {
height: 300px;
width: 320px;
overflow-y: auto;
scroll-snap-type: y mandatory;
${paddingRule}
border: 1px solid #345;
}
#fixed-header {
position: fixed;
top: 0;
left: 0;
z-index: 1;
width: 320px;
height: 50px;
padding: 14px 12px;
background: #172554;
color: white;
font: 16px sans-serif;
}
section {
height: 300px;
scroll-snap-align: start;
padding: 0 12px;
font: 16px sans-serif;
}
section:nth-child(odd) { background: #dbeafe; }
section:nth-child(even) { background: #dcfce7; }
h2 { margin: 0; padding-top: 0; line-height: 50px; }
</style>
</head>
<body>
<header id="fixed-header">Fixed header (50px)</header>
<main id="scroller" tabindex="0" aria-label="Snapped sections">
<section id="first"><h2>First section</h2></section>
<section id="second"><h2>Second section</h2></section>
<section id="third"><h2>Third section</h2></section>
</main>
<script>
window.snapToSection = function snapToSection(name) {
const section = document.getElementById(name);
const scroller = document.getElementById('scroller');
if (!section || !['first', 'second', 'third'].includes(name)) {
throw new RangeError('Unknown snap target: ' + name);
}
// offsetTop includes the scroller border, while snapping is calculated from
// its scrollable padding edge. Account for both that border and the
// container-owned scroll padding before stopping short of the snap point.
const scrollPaddingTop = parseFloat(getComputedStyle(scroller).scrollPaddingTop) || 0;
const targetTop = section.offsetTop - scroller.offsetTop - scroller.clientTop - scrollPaddingTop;
// Stop slightly before the adjusted target so mandatory snapping chooses
// the container's actual snap point rather than relying on border offsets.
scroller.scrollTo({ top: targetTop - 12 });
};
</script>
</body>
</html>`;
}
SourcesMDN: CSS Scroll Snap guide (opens a new tab)MDN: scroll-snap-type (opens a new tab)MDN: Basic concepts of scroll snap (opens a new tab)
A mandatory snap can still bury the heading under the fixed bar
The fixture is intentionally small. A 300px-tall scroll container holds three 300px sections, each with a heading at the top, and the container uses `scroll-snap-type: y mandatory`. The header is fixed at the top of the viewport and occupies 50px. When the second section is chosen, the browser snaps the section start to the top of the scrollport, but the fixed header still occupies the first 50px of the viewport. The heading is therefore hidden behind it even though the snap itself succeeded.
This is the failure that can mislead you if you only inspect the scroll offset. The container is on the intended section. The heading is not visible. Because the snap target and the visible target are not the same thing, the apparent success of `scroll-snap-type` hides the overlap bug. You can make the snap strictness looser or tighter and still keep the same layout problem, because strictness does not define where the browser should reserve space for overlapping chrome.
The negative case is important here: changing the child element's `scroll-snap-align` does not solve the hidden-heading problem by itself when the child already aligns where you want it. The alignment is not wrong; the viewport's usable area is too small for the fixed header.
SourcesMDN: Basic concepts of scroll snap (opens a new tab)MDN: scroll-snap-type (opens a new tab)
Reserve the missing space on the scroll container, not on the child
`scroll-padding-top` belongs on the scroll container because the container owns the snapport. That property tells the browser that the top of the usable snapping area begins below the fixed header. The snap target can stay aligned to `start`, and the snapping can stay `mandatory`; only the container's effective region changes. That is the correct repair when the issue is overlap, not alignment.
This is also why `scroll-margin-top` is not the same answer. Margin on the child creates extra room around that child, which can help in other scenarios, but the visual promise in this fixture is about a shared overlay that affects every snap target. The header is not special to one section, so the offset belongs to the container that must account for the header. A container-level padding offset keeps the content model simple: every target snaps into the same adjusted viewport.
The useful mental model is that `scroll-padding` moves the browser's notion of where a good snap should land. It does not move the content itself, and it does not soften snap strictness. The section's own geometry stays intact; only the browser's landing zone changes.
SourcesMDN: Basic concepts of scroll snap (opens a new tab)MDN: scroll-snap-type (opens a new tab)
The child content does not move, and the snap rule does not change
The repaired fixture keeps the same scroll axis, the same `mandatory` strictness, and the same `scroll-snap-align: start` on each section. That is deliberate. If you change too many variables at once, the fix becomes harder to reason about. Here, the only changed rule is `scroll-padding-top` on the container. The headings still sit at the top of their sections; the browser simply stops the snapped section lower in the viewport so the fixed header no longer covers the title.
That distinction helps you read regressions accurately. If the heading appears lower after the fix, that is not because the section changed shape. It is because the container's optimal viewing region was shifted. The section's internal layout remains the same, which is important when the same child content needs to align with other page interactions or when you rely on the section's top edge for anchoring, internal spacing, or testing.
This is also why the test checks both geometry and CSS values. It asserts that the scroll container still reports `y mandatory`, that the section still reports `start`, and that the heading's top edge is no longer hidden under the header in the repaired case. The repair preserves the snap model instead of replacing it with a different one.
SourcesMDN: Basic concepts of scroll snap (opens a new tab)MDN: scroll-snap-type (opens a new tab)
What the browser test proves, and what it leaves open
The controlled browser test exercises the exact boundary that matters here: the second section is snapped, and the heading is measured against the fixed header's bottom edge. In the broken case, the snapped heading lands under the header. In the repaired case, the heading lands below the header while the child content and snap strictness remain unchanged. The test also checks the first section as a boundary case, because a scroll start cannot be offset upward forever. That preserves an honest limit: a header offset can reserve room for later snap targets, but it cannot create negative scroll space above the first item.
The test does not claim broader accessibility or performance guarantees. It does not prove that every browser implementation will make the same fine-grained snap decision under every user gesture. It does prove the CSS contract in the fixture used here: the scroll container's own padding affects where the snapped target becomes visible. That is the right boundary for a layout repair article.
A useful side effect of the fixture is that it also shows what not to over-interpret. The heading being visible is the outcome to check; the scroll offset number is only a supporting signal. A correct snap can occur at more than one pixel value depending on borders, fonts, and viewport geometry. The geometric relationship between the header and the heading is the durable assertion.
import test from 'node:test';
import assert from 'node:assert/strict';
import { chromium } from 'playwright';
import { snapFixture } from './main.mjs';
async function withPage(html, callback) {
const browser = await chromium.launch({
headless: true,
args: ['--no-sandbox'],
});
try {
const page = await browser.newPage({ viewport: { width: 500, height: 400 } });
await page.route('**/*', (route) => route.abort());
await page.setContent(html);
await page.locator('#scroller').focus();
await page.waitForFunction(() => document.activeElement?.id === 'scroller');
await page.keyboard.press('ArrowDown');
return await callback(page);
} finally {
await browser.close();
}
}
async function snapAndRead(page, name, expectedScrollTop) {
await page.evaluate((target) => window.snapToSection(target), name);
await page.waitForFunction(
(expected) => Math.abs(document.getElementById('scroller').scrollTop - expected) < 2,
expectedScrollTop,
);
return page.evaluate((target) => {
const header = document.getElementById('fixed-header').getBoundingClientRect();
const heading = document.querySelector(`#${target} h2`).getBoundingClientRect();
const section = document.getElementById(target);
const scroller = document.getElementById('scroller');
return {
headerBottom: header.bottom,
headingTop: heading.top,
scrollTop: scroller.scrollTop,
snapType: getComputedStyle(scroller).scrollSnapType,
snapAlign: getComputedStyle(section).scrollSnapAlign,
headingOffsetInsideSection: section.querySelector('h2').offsetTop - section.offsetTop,
elementAtHeading: document.elementFromPoint(heading.left + 4, heading.top + 4)?.id,
};
}, name);
}
test('without scroll-padding, mandatory snapping places the second heading beneath the fixed header', async () => {
await withPage(snapFixture(), async (page) => {
const result = await snapAndRead(page, 'second', 300);
assert.equal(result.snapType, 'y mandatory');
assert.equal(result.snapAlign, 'start');
assert.ok(result.headingTop < result.headerBottom);
assert.equal(result.elementAtHeading, 'fixed-header');
});
});
test('scroll-padding on the scroll container keeps the snapped second heading below the header', async () => {
await withPage(snapFixture({ scrollPadding: true }), async (page) => {
const result = await snapAndRead(page, 'second', 250);
assert.equal(result.snapType, 'y mandatory');
assert.equal(result.snapAlign, 'start');
assert.ok(result.headingTop >= result.headerBottom);
assert.equal(result.headingOffsetInsideSection, 0);
});
});
test('the first target is a scroll-start boundary and cannot receive a negative scroll-padding offset', async () => {
await withPage(snapFixture({ scrollPadding: true }), async (page) => {
await assert.rejects(
page.evaluate(() => window.snapToSection('missing')),
/Unknown snap target: missing/,
);
const result = await snapAndRead(page, 'first', 0);
assert.equal(result.scrollTop, 0);
assert.ok(result.headingTop < result.headerBottom);
assert.equal(result.elementAtHeading, 'fixed-header');
});
});
SourcesMDN: Using scroll snap events (opens a new tab)MDN: Basic concepts of scroll snap (opens a new tab)
When this fix is enough, and when another property is the better fit
Use `scroll-padding` when the problem is shared chrome that changes the usable viewport for all snap targets. A fixed header, a persistent subnavigation bar, or a docked toolbar all fit that pattern. The offset belongs to the scroll container because the container is the thing that needs to account for the reserved space. If the problem is not shared chrome, or if different targets need different offsets, `scroll-margin` on the children may be a better fit.
There are also cases where scroll snap is the wrong tool entirely. If the application needs the heading to appear in a precise place because some other script reads its position, or if the content is too short for a meaningful snap sequence, the fix is not to keep tuning snap rules. It is to choose a different interaction model. Scroll snap is for controlled navigation through a scrollable set of targets, not for making arbitrary content land exactly under arbitrary overlays.
The practical decision rule is simple: when the content is already snapping correctly but the viewport is lying about what is visible, adjust the container's optimal viewing region. When the target itself needs bespoke spacing, use child margins. When neither describes the problem, stop and reframe the interaction before you keep stacking snap properties onto the wrong layer.
SourcesMDN: scroll-snap-type (opens a new tab)MDN: Basic concepts of scroll snap (opens a new tab)MDN: CSS Scroll Snap guide (opens a new tab)
Keep the snap, move the viewport
If a snapped target disappears under a fixed header, the browser is usually not failing to snap. The container is landing exactly where it was told to land. The missing piece is the scroll container's own view of how much top space is already occupied. `scroll-padding-top` lets you reserve that space without weakening the snap behavior or moving the child content.
That makes the repair easy to remember: keep `scroll-snap-type` and `scroll-snap-align` as they are, then add the offset where the scroll container owns the viewport. The section still snaps. The header still stays fixed. The difference is that the snapped heading now has somewhere to be seen.
For this kind of overlap, the right fix is not a new snap target. It is a better snapport.
SourcesMDN: Basic concepts of scroll snap (opens a new tab)MDN: scroll-snap-type (opens a new tab)


