CSS scroll-margin-block Property

What You’ll Learn

The scroll-margin-block property sets scroll offsets on the block axis. It is the logical companion to physical top/bottom scroll margins and works well with scroll snapping and anchor navigation.

Introduction

The scroll-margin-block property in CSS is used to adjust the scroll snap area at the block start and block end of an element.

This property is particularly useful when implementing scroll snapping in a vertical writing mode or when you need to add margins to the scroll snap position. By using this property, you can control the proximity of elements to the container’s scroll position, enhancing the scrolling experience.

Definition and Usage

scroll-margin-block is a logical shorthand for scroll-margin-block-start and scroll-margin-block-end. Apply it to the element that becomes a scroll target.

In standard horizontal writing mode, block-start maps to the top and block-end maps to the bottom. That makes scroll-margin-block: 4rem 1rem similar to setting top and bottom scroll offsets, but it stays correct if the writing mode changes.

📝 Syntax

The syntax for the scroll-margin-block property is straightforward and allows you to specify the margin for the block start and block end.

element {
  scroll-margin-block: block-start block-end;
}

Here, block-start and block-end can be any valid CSS length value (e.g., px, em, rem) or a percentage.

Basic Example

section {
  scroll-margin-block: 20px;
}

Longhand Properties

• scroll-margin-block-start — offset at the block-start edge
• scroll-margin-block-end — offset at the block-end edge

Syntax Rules

• One value sets both block-start and block-end equally.
• Two values set block-start first, then block-end.
• Percentages are relative to the element’s block size.
• Works with anchor links, scrollIntoView(), and scroll snapping.

🎯 Default Value

The default value of the scroll-margin-block property is 0, meaning no additional margin is added to the scroll snap area.

💎 Property Values

When to Use scroll-margin-block

scroll-margin-block is the right choice when block-axis scroll offsets should follow logical layout:

• Scroll snapping — Keep snapped sections away from container edges.
• Sticky headers — Offset block-start so titles stay visible below fixed UI.
• International layouts — Prefer logical properties over hard-coded top/bottom rules.
• Documentation pages — Fine-tune where chapter anchors land vertically.

For left/right offsets, use scroll-margin-inline instead.

Examples Gallery

Start with the reference scroll-snap example, set different block-start and block-end values, try a scroll container, and use scroll-margin-block-start with a sticky header.

<style>
  html {
    scroll-snap-type: y mandatory;
  }

  section {
    height: 100vh;
    scroll-snap-align: start;
    scroll-margin-block: 20px;
  }
</style>

<section>Section 1</section>
<section>Section 2</section>
<section>Section 3</section>

section[id] {
  scroll-margin-block: 4rem 1.5rem;
}

.panel {
  scroll-snap-align: start;
  scroll-margin-block: 16px;
}

article {
  scroll-margin-block-start: 3.5rem;
}

scroll-margin-block vs scroll-margin

scroll-margin is the physical shorthand for all four sides. scroll-margin-block targets only the block axis and is safer for multilingual layouts.

Pair with scroll-behavior: smooth for animated anchor navigation and with scroll-snap-align for snapped carousels or section scrollers.

/* Physical shorthand */
.physical { scroll-margin-top: 4rem; }

/* Logical equivalent in horizontal writing */
.logical { scroll-margin-block-start: 4rem; }

💡 Best Practices