The scroll-margin-block property defines an offset along an element’s block axis that browsers use when bringing that element into view — whether by user-initiated fragment navigation, programmatic scrolling methods, or scroll snapping. It effectively tells the browser to stop scrolling short of the element’s border box by the specified offset on the block-start and/or block-end side(s), so the element appears separated from the container edge by that space. Importantly, this change is only used when calculating the final scroll position; it does not change the element’s layout or the surrounding flow.

When an element is targeted (for example by an anchor, an API like element.scrollIntoView, or a snap point), the offset created by scroll-margin-block is applied to the computed intersection point so the element does not end up flush against the viewport or scrolling container edge. This makes it useful for keeping pinned headers, overlays, or other UI chrome from covering anchored content. The property works together with scroll-alignment behavior, so it affects how elements line up relative to snapping rules such as those controlled by scroll-snap-align.

Because scroll-margin-block is a logical property, it follows the writing mode and block axis of the document: the direction it offsets is determined by the element’s block direction rather than a physical top/bottom axis. That means switching writing modes or vertical text flows will change which physical edge the offset applies to, so consider the document’s writing-mode when designing layouts for international or rotated text. Also note the distinction between this scrolling offset and layout margins — properties like margin-block affect layout and box size, whereas scroll-margin-block only affects scroll targeting.

In practical use, authors often combine scroll-margin-block with container-level adjustments to scrolling behavior: for instance, setting a container’s inner offset with scroll-padding or controlling animation of the scroll with scroll-behavior. Because it participates in visibility and hit-testing computations only at scroll time, you can use it to create consistent visual spacing for anchored content without reflowing the page. Keep in mind that interactions with snapping, overlays, and dynamic UI changes may require testing across different writing directions and complex layout scenarios.