CSS scroll-margin-block-start Property

Code Examples

A basic scroll-snap example where each section stops 50 pixels below the top of the container.

<style>
  .container {
    height: 300px;
    overflow-y: scroll;
    scroll-snap-type: y mandatory;
    border: 2px solid #333333;
  }
  section {
    height: 300px;
    scroll-snap-align: start;
    /* This creates a 50px gap at the top when snapping */
    scroll-margin-block-start: 50px;
  }
  .one { background: #ff5555; }
  .two { background: #55ff55; }
</style>
<div class="container">
  <section class="one">Section 1</section>
  <section class="two">Section 2</section>
</div>

A semantic example using a fixed header and a dynamic offset calculation, demonstrating how the property works with both anchor links and JavaScript scroll methods.

<style>
  :root {
    --nav-height: 60px;
  }
  header {
    position: fixed;
    top: 0;
    height: var(--nav-height);
    width: 100%;
    background: #222222;
    color: #ffffff;
    z-index: 10;
  }
  article {
    margin-top: var(--nav-height);
  }
  h2 {
    /* Offset the heading so it is not hidden under the fixed header */
    scroll-margin-block-start: calc(var(--nav-height) + 20px);
    background: #eeeeee;
  }
</style>
<header>Fixed Navigation Bar</header>
<nav>
  <a href="#topic1">Go to Topic 1</a>
</nav>
<article>
  <div style="height: 1000px;">Scroll down or click the link...</div>
  <h2 id="topic1">Topic 1</h2>
  <p>Content for topic 1 starts here.</p>
  <button onclick="scrollToTopic()">JS Scroll</button>
</article>
<script>
function scrollToTopic() {
  document.getElementById("topic1").scrollIntoView({ behavior: "smooth" });
}
</script>

Pro Tip

You can use CSS variables to manage this offset globally. If your header height changes at different breakpoints, update a single variable like --header-height, and use scroll-margin-block-start: var(--header-height); on all your section headings. This keeps your code clean and your offsets consistent across the entire application.