Scroll-margin - CSS Property

Syntax diagram of scroll-margin.

Description of the scroll-margin property.

The property scroll-margin can be used in the context of scrolling with snaps. It defines the margins around snap points. Refer to our more general explanations on scrolling with snaps. The property applies to elements that are defined as snap points.

Do not confuse with regular margins (see margin): these apply between successive elements. Whereas scrolling margins are positioned between an element and the edge of the scrolling container.

The examples below illustrate the effect of the scroll-margin property. These are two scrolling containers with snapping. When scrolling through the content, you will notice that, indeed, the scrolling always stops on an image positioned at the top of the container. In the first example, no scroll margin has been set: the images are stuck to the beginning of the container, with no space, which is not very aesthetically pleasing. In the second example, a scroll margin is present.

 
 

No scroll margins

 
 

With scroll margins

The property scroll-margin is a shorthand property. It is possible to individually define each of the margins with the four properties below. These properties are called "physical" because they are independent of the writing mode.

• scroll-margin-top: Sets the top margins of the scroll window in the context of scroll snapping.
• scroll-margin-right: Sets the right margins of the scroll window in the context of scroll snapping.
• scroll-margin-bottom: Sets the margins at the bottom of the scroll window in the context of scrolling with snapping.
• Scroll-margin-left: Sets the margins at the top of the scroll window in the context of scrolling with snapping.

Also see the following properties:

Prise en charge du mode d'écriture.

If the text is not in a Latin language, it is recommended to use logical properties instead, which adapt to the writing mode:

• scroll-margin-block-start: corresponds to the top scrolling margin for Latin languages.
• scroll-margin-block-end: the bottom scrolling margin for Latin languages.
• scroll-margin-inline-start: the left scroll margin for Latin languages.
• scroll-margin-inline-end: the right scroll margin for Latin languages.
• scroll-margin-block: shorthand property, defines the start of block and end of block margins.
• scroll-margin-inline: shorthand property, sets the start of line and end of line margins.

Values for scroll-margin.

• scroll-margin: 20px; scroll-margin: 20px 10px; scroll-margin: 20px 10px 15px; scroll-margin: 20px 10px 15px 15px;

  All values must be followed by one of CSS dimension units. Percentages are not allowed. Four values are accepted, but it is possible not to specify all of them. Here is how the values are assigned depending on their number:

  • If only one value is specified, it applies equally to all four margins.
  • If two values are specified, the first defines the top and bottom margins, and the second value defines the left and right margins.
  • When three values are specified, they define respectively the top margin, the left and right margins, and the bottom margin.
  • Finally, if all four values are specified, they each define margins, in the following order: top margin, right margin, bottom margin, left margin.
  
  A single value

  
  Two values

  
  Three values

  
  Four values

  To modify only one of the margins, it is possible to use the detailed properties (scroll-margin-top for example).

• scroll-margin: initial; (0) scroll-margin: inherit; scroll-margin: revert; scroll-margin: revertLayer; scroll-margin: unset;

  Common values ​​are presented on these pages: initial, inherit, revert, revert-layer, unset.

Animation of the scroll-margin property.

The property scroll-margin can be animated, but it seems that browsers have trouble achieving this feat: on Firefox   the animation does not occur at all; on Edge   and Chrome  , it happens abruptly, contrary to what is provided by the W3C specification.

Visually, the animation of scroll-margin varies the offset between the content and the scrolling container. This offset is visible even in the absence of any user action to scroll the content.

 
 

Access the scroll-margin property via a program

Change the scrolling margins with Javascript.

In JavaScript, here is how to modify the scroll margins, in other words the value of scroll-margin. There are two syntaxes, the first using the style array and the typical CSS notation (the property name written in kebab-case), and the second, with an object notation and the property name written in camel-case.

let el = document.getElementById('id'); el.style['scroll-margin'] = '10mm'; // or let el = document.getElementById('id'); el.style.scrollMargin = '10mm';

With Javascript, read the value of scroll-margin.

The code below retrieves the value of scroll-margin when it has been set in the HTML code, with the style attribute, and not by using a CSS selector.

let el = document.getElementById('id'); let value = el.style['scroll-margin']; // or let el = document.getElementById('id'); let value = el.style.scrollMargin;

With Javascript, read the computed value of scroll-margin.

The computed value is either the one that is assigned directly to the element, via its style attribute or via a CSS selector, or the one that results from the cascade of inheritances, or again, it will be the initial value of the property (0 for scroll-margin). In all cases, the computed value is defined.

let el = document.getElementById('id'); let value = window.getComputedStyle(el).getPropertyValue('scroll-margin');

With JQuery, change the value of scroll-margin.

JQuery is a library that is less used now (particularly because of the new features of CSS). However, we provide the syntaxes to write a value in scroll-margin or to read back its computed value..


$('#id').css('scroll-margin', '10mm');
// or
$('#id').css('scrollMargin', '10mm');


With JQuery, read the computed value of scroll-margin.

let value = $('#id').css('scroll-margin');

Test it yourself.

The buttons below apply the entered value to the scroll-margin property and then display either the value as it was applied or the computed value. This second option allows you to see how the value of scroll-margin is stored (serialized). In particular, it is observed that all absolute or relative units are converted to pixels.

Browsers compatibility with scroll-margin.

Support for the scroll-margin property is correct on all current browsers.

1

Scroll Snap

2

scroll-margin
property

Estimated overall support.

96%

95%

Browsers on computers :

Mobile browsers :

Outdated or marginal browsers :

Internet Explorer

UC Browser pour Androïd

Opéra Mobile

QQ Browser

Baidu Browser

Opéra

Samsung Internet

Firefox pour Androïd

Edge

Firefox

Chrome pour Androïd

Androïd Brower

Safari

Safari sur IOS

Chrome

KaiOS Browser

Opéra mini

See Caniuse.com for more compatibility information.

Caniuse

Caniuse

Historic of the scroll-margin property.

• CSS Scroll Snap Module - Level 1

  This specification module defines the features regarding scrolling with snap positions. In other words, content-aligned scrolling, to prevent, for example, an image from being cut off at the top or bottom of its container.

  Regarding scroll-margin. First presentation of the scroll-margin property.
  

  March 26, 2015

  Working Draft.

  

  October 20, 2016

  Candidate Recommendation.

  

  

See also, regarding scrolling with snapping.

Scrolling with snapping is described in the CSS Scroll Snap Module. The property scroll-margin and all those related to the subject are also present in this module:

Properties: