scroll-margin-top

Overview

The scroll-margin-top property is used to establish a top scroll margin (outset) for an element. This margin adjusts the element's scroll snap area, which is the region influencing its alignment when snapped. The snapping process occurs in relation to the snapport — the area within the scroll container's scrollport used as the alignment container for the scroll snap areas when calculating snap positions.

Note: scroll-margin-top is part of the scroll-margin shorthand, which also includes scroll-margin-right, scroll-margin-bottom, and scroll-margin-left.

Examples and Usage

In the demonstration below, we'll work with a scroll container that has four child elements. Each child element will have a scroll margin defined for the top edge of their respective scroll snap areas. The scroll container is designed to enforce scroll-snapping behavior.

HTML Structure

<div class="scroll-container">
  <div class="scroll-item item-1"><span>1</span></div>
  <div class="scroll-item item-2"><span>2</span></div>
  <div class="scroll-item item-3"><span>3</span></div>
  <div class="scroll-item item-4"><span>4</span></div>
</div>

CSS Styling

.scroll-container {
  width: 300px; /* Sets the width of the scroll container */
  height: 300px; /* Sets the height of the scroll container */
  border: 2px solid black; /* Adds a border around the scroll container for visualization */
  overflow-y: scroll; /* Enables vertical scrolling */
  overflow-x: hidden; /* Disables horizontal scrolling */
  scroll-snap-type: y mandatory; /* Enforces vertical scrolling with mandatory snapping */
}

.scroll-item {
  width: 300px; /* Sets the width of each scroll item */
  height: 300px; /* Sets the height of each scroll item */
  scroll-snap-align: start; /* Aligns snapping to the start edge of the item */
  scroll-margin-top: 30px; /* Defines a scroll margin at the top of the scroll snap area */
}

.scroll-item span {
  display: flex; /* Utilizes flexbox for center alignment */
  justify-content: center; /* Horizontally centers content */
  align-items: center; /* Vertically centers content */
  height: 100%; /* Takes the full height of the parent */
  font-size: 3em; /* Sets the font size */
  color: black; /* Sets the font color */
  font-family: "UI Monospace", monospace; /* Defines the font family */
}

.item-1,
.item-3 {
  background-color: orange; /* Sets the background color for items 1 and 3 */
}

.item-2,
.item-4 {
  background-color: lightblue; /* Sets the background color for items 2 and 4 */
}

So, the scroll container is set to a specific width and height and contains four child elements. Each child element, also referred to as a scroll item, has a defined scroll margin at the top of its scroll snap area set by scroll-margin-top. This scroll margin influences how the browser aligns this element to the snapport of the scroll container during a scroll operation.

The property scroll-snap-type set to y mandatory enforces vertical scroll snapping within the container. This means the scroll operation will stop at a defined snap point, which is influenced by the scroll-margin-top and scroll-snap-align properties on the child elements.

For each scroll item, scroll-snap-align is set to start. This value informs the browser to align the start edge of the snap area (which includes the scroll-margin-top space) to the snapport when snapping occurs.

This differs from scroll-padding properties in a significant way: while scroll-padding adjusts the scroll snap area for the scroll container, scroll-margin properties like scroll-margin-top adjust the scroll snap area for the individual child elements inside the container.

Lastly, the colors and font stylings in the example are used for visual differentiation and do not influence snapping behavior.

Values

The scroll-margin-top property accepts the following values:

Associated Properties

• scroll-margin
• scroll-margin-right
• scroll-margin-bottom
• scroll-margin-left
• scroll-margin-inline
• scroll-margin-block
• scroll-padding
• scroll-padding-inline
• scroll-padding-block
• scroll-snap-type
• scroll-snap-align

Tips and Tricks

• The scroll-margin-top property allows us to control the scroll snapping behavior for the top edge of an element within a scroll container. It does not affect the layout, meaning it doesn't push other elements away as a regular margin would.

• Unlike the scroll-padding properties, which affect the scroll container's snapport, the scroll-margin properties modify the scroll snap area of the elements inside the scroll container. In a sense, scroll-margin properties set the snapping alignment for child elements, whereas scroll-padding properties determine the snapping area within the parent container.

• Remember to pair scroll-margin-top with a suitable scroll-snap-align value. For example, when scroll-snap-align is set to start in a vertical scrolling context, the snapping happens at the top edge of the snap area, influenced by scroll-margin-top.

• The terms "scroll container" and "scroll snap container" are often used interchangeably. However, not all scroll containers are scroll snap containers. A scroll container becomes a scroll snap container when scroll snapping is enforced via the scroll-snap-type property. A scroll snap container, therefore, is a scroll container with scroll snapping behavior enabled.

• When calculating the scroll snap area, the scroll-margin-top value determines the margin for the top edge of the area. This value is added to the element's size to create an "outset" from the element itself, establishing the space within which scroll snapping can occur.

Browser Compatibility

For a more detailed breakdown and specific context on older versions of Safari, refer to the first link in the Useful Resources below.

Caution: Internet Explorer support data may be incorrect since MDN browser-compat-data no longer updates it. Also, early Edge versions used EdgeHTML, leading to mismatched version numbers. From version 79, Edge uses Chromium with matching version numbers.

Useful Resources

Can I use: scroll-margin-top

W3C's Editor's Draft of CSS Scroll Snap Module Level 1: Physical Longhands for scroll-margin