Skip to main contentSkip to docs navigation
View on GitHub

Margin

Responsive utilities for applying margin on all sides, axes, or individual edges using the Chassis spacing scale.

On this page
@layer utilities
MDN Reference
Scoped tokens

Overview

Margin utilities apply the CSS margin property and its logical shorthand variants. All classes are responsive by default and cover all four sides at once, an axis (inline or block), or a single edge.

For flex and grid layouts, gap utilities are more appropriate than margins for spacing between items — they avoid the double-margin problem on wrapped rows.

Notation

Margin classes that apply at all breakpoints have no breakpoint prefix — they start from min-width: 0 and are not media-query-bound. Breakpoint-prefixed classes apply at that breakpoint and above.

The classes are named using the format m{sides}-{size} for xsmall and {breakpoint}:m{sides}-{size} for small, medium, large, xlarge, and 2xlarge.

Where sides is one of:

  • x — margin-inline (both inline edges)
  • y — margin-block (both block edges)
  • t — margin-block-start
  • b — margin-block-end
  • s — margin-inline-start
  • e — margin-inline-end
  • (blank) — margin on all four sides

Where size is one of:

  • zero or 0 — eliminates margin by setting it to 0
  • 4xsmall — default token value is 0.0625rem (1px).
  • 3xsmall — default token value is 0.125rem (2px).
  • 2xsmall — default token value is 0.25rem (4px).
  • xsmall — default token value is 0.5rem (8px).
  • medium — default token value is 1rem (16px).
  • large — default token value is 1.25rem (20px).
  • xlarge — default token value is 1.5rem (24px).
  • 2xlarge — default token value is 1.75rem (28px).
  • 3xlarge — default token value is 2rem (32px).
  • 4xlarge — default token value is 2.25rem (36px).
  • 5xlarge — default token value is 2.5rem (40px).
  • 6xlarge — default token value is 3rem (48px).
  • auto — sets the margin to auto

Additional sizes can be added by adding entries to the $spaces Sass map.

All sides

.m-{size} sets margin on all four sides of an element at once.

m-xsmall
m-small
m-medium
m-large
HTML
<div class="overflow-auto">
  <div class="m-xsmall">m-xsmall</div>
  <div class="m-small">m-small</div>
  <div class="m-medium">m-medium</div>
  <div class="m-large">m-large</div>
</div>

Axes

Axis utilities apply margin to two opposite edges simultaneously. .mx-{size} targets both inline edges; .my-{size} targets both block edges.

my-large
mx-large
HTML
<div class="overflow-auto">
  <div class="my-large">my-large</div>
  <div class="mx-large">mx-large</div>
</div>

Individual edges

Single-edge utilities set margin on one edge without affecting the others.

mt-large
mb-large
ms-large
me-large
HTML
<div class="overflow-auto">
  <div class="mt-large">mt-large</div>
  <div class="mb-large">mb-large</div>
  <div class="ms-large">ms-large</div>
  <div class="me-large">me-large</div>
</div>

Horizontal centering

.mx-auto centers a fixed-width block element by setting its inline margins to auto. The element must have display: block and an explicit width.

Centered element
HTML
<div class="overflow-auto">
  <div class="mx-auto" style="width: 200px;">Centered element</div>
</div>

Negative margins

Negative margin utilities mirror the positive spacing scale and are enabled by default. Setting $enable-negative-margins: false in Sass removes them from the compiled output.

Negative classes follow the same sides notation, prefixed with -. -mt-medium is the inverse of mt-medium, and -mx-small is the inverse of mx-small. All negative utilities are responsive and support the same breakpoint prefixes as their positive counterparts.

-mx-medium
-my-medium
HTML
<div class="p-medium">
  <div class="-mx-medium">-mx-medium</div>
  <div class="-my-medium">-my-medium</div>
</div>

CSS

Margin utilities are generated from Sass maps built on design token values via the utilities API.

Reference

The table lists all margin utilities and their CSS properties.

ClassProperties
.m-zeromargin: var(--cx-space-zero);
.m-4xsmallmargin: var(--cx-space-4xsmall);
.m-3xsmallmargin: var(--cx-space-3xsmall);
.m-2xsmallmargin: var(--cx-space-2xsmall);
.m-xsmallmargin: var(--cx-space-xsmall);
.m-smallmargin: var(--cx-space-small);
.m-mediummargin: var(--cx-space-medium);
.m-largemargin: var(--cx-space-large);
.m-xlargemargin: var(--cx-space-xlarge);
.m-2xlargemargin: var(--cx-space-2xlarge);
.m-3xlargemargin: var(--cx-space-3xlarge);
.m-4xlargemargin: var(--cx-space-4xlarge);
.m-5xlargemargin: var(--cx-space-5xlarge);
.m-6xlargemargin: var(--cx-space-6xlarge);
.m-0margin: 0;
.m-automargin: auto;
.mx-zeromargin-inline: var(--cx-space-zero);
.mx-4xsmallmargin-inline: var(--cx-space-4xsmall);
.mx-3xsmallmargin-inline: var(--cx-space-3xsmall);
.mx-2xsmallmargin-inline: var(--cx-space-2xsmall);
.mx-xsmallmargin-inline: var(--cx-space-xsmall);
.mx-smallmargin-inline: var(--cx-space-small);
.mx-mediummargin-inline: var(--cx-space-medium);
.mx-largemargin-inline: var(--cx-space-large);
.mx-xlargemargin-inline: var(--cx-space-xlarge);
.mx-2xlargemargin-inline: var(--cx-space-2xlarge);
.mx-3xlargemargin-inline: var(--cx-space-3xlarge);
.mx-4xlargemargin-inline: var(--cx-space-4xlarge);
.mx-5xlargemargin-inline: var(--cx-space-5xlarge);
.mx-6xlargemargin-inline: var(--cx-space-6xlarge);
.mx-0margin-inline: 0;
.mx-automargin-inline: auto;
.my-zeromargin-block: var(--cx-space-zero);
.my-4xsmallmargin-block: var(--cx-space-4xsmall);
.my-3xsmallmargin-block: var(--cx-space-3xsmall);
.my-2xsmallmargin-block: var(--cx-space-2xsmall);
.my-xsmallmargin-block: var(--cx-space-xsmall);
.my-smallmargin-block: var(--cx-space-small);
.my-mediummargin-block: var(--cx-space-medium);
.my-largemargin-block: var(--cx-space-large);
.my-xlargemargin-block: var(--cx-space-xlarge);
.my-2xlargemargin-block: var(--cx-space-2xlarge);
.my-3xlargemargin-block: var(--cx-space-3xlarge);
.my-4xlargemargin-block: var(--cx-space-4xlarge);
.my-5xlargemargin-block: var(--cx-space-5xlarge);
.my-6xlargemargin-block: var(--cx-space-6xlarge);
.my-0margin-block: 0;
.my-automargin-block: auto;
.mt-zeromargin-block-start: var(--cx-space-zero);
.mt-4xsmallmargin-block-start: var(--cx-space-4xsmall);
.mt-3xsmallmargin-block-start: var(--cx-space-3xsmall);
.mt-2xsmallmargin-block-start: var(--cx-space-2xsmall);
.mt-xsmallmargin-block-start: var(--cx-space-xsmall);
.mt-smallmargin-block-start: var(--cx-space-small);
.mt-mediummargin-block-start: var(--cx-space-medium);
.mt-largemargin-block-start: var(--cx-space-large);
.mt-xlargemargin-block-start: var(--cx-space-xlarge);
.mt-2xlargemargin-block-start: var(--cx-space-2xlarge);
.mt-3xlargemargin-block-start: var(--cx-space-3xlarge);
.mt-4xlargemargin-block-start: var(--cx-space-4xlarge);
.mt-5xlargemargin-block-start: var(--cx-space-5xlarge);
.mt-6xlargemargin-block-start: var(--cx-space-6xlarge);
.mt-0margin-block-start: 0;
.mt-automargin-block-start: auto;
.me-zeromargin-inline-end: var(--cx-space-zero);
.me-4xsmallmargin-inline-end: var(--cx-space-4xsmall);
.me-3xsmallmargin-inline-end: var(--cx-space-3xsmall);
.me-2xsmallmargin-inline-end: var(--cx-space-2xsmall);
.me-xsmallmargin-inline-end: var(--cx-space-xsmall);
.me-smallmargin-inline-end: var(--cx-space-small);
.me-mediummargin-inline-end: var(--cx-space-medium);
.me-largemargin-inline-end: var(--cx-space-large);
.me-xlargemargin-inline-end: var(--cx-space-xlarge);
.me-2xlargemargin-inline-end: var(--cx-space-2xlarge);
.me-3xlargemargin-inline-end: var(--cx-space-3xlarge);
.me-4xlargemargin-inline-end: var(--cx-space-4xlarge);
.me-5xlargemargin-inline-end: var(--cx-space-5xlarge);
.me-6xlargemargin-inline-end: var(--cx-space-6xlarge);
.me-0margin-inline-end: 0;
.me-automargin-inline-end: auto;
.mb-zeromargin-block-end: var(--cx-space-zero);
.mb-4xsmallmargin-block-end: var(--cx-space-4xsmall);
.mb-3xsmallmargin-block-end: var(--cx-space-3xsmall);
.mb-2xsmallmargin-block-end: var(--cx-space-2xsmall);
.mb-xsmallmargin-block-end: var(--cx-space-xsmall);
.mb-smallmargin-block-end: var(--cx-space-small);
.mb-mediummargin-block-end: var(--cx-space-medium);
.mb-largemargin-block-end: var(--cx-space-large);
.mb-xlargemargin-block-end: var(--cx-space-xlarge);
.mb-2xlargemargin-block-end: var(--cx-space-2xlarge);
.mb-3xlargemargin-block-end: var(--cx-space-3xlarge);
.mb-4xlargemargin-block-end: var(--cx-space-4xlarge);
.mb-5xlargemargin-block-end: var(--cx-space-5xlarge);
.mb-6xlargemargin-block-end: var(--cx-space-6xlarge);
.mb-0margin-block-end: 0;
.mb-automargin-block-end: auto;
.ms-zeromargin-inline-start: var(--cx-space-zero);
.ms-4xsmallmargin-inline-start: var(--cx-space-4xsmall);
.ms-3xsmallmargin-inline-start: var(--cx-space-3xsmall);
.ms-2xsmallmargin-inline-start: var(--cx-space-2xsmall);
.ms-xsmallmargin-inline-start: var(--cx-space-xsmall);
.ms-smallmargin-inline-start: var(--cx-space-small);
.ms-mediummargin-inline-start: var(--cx-space-medium);
.ms-largemargin-inline-start: var(--cx-space-large);
.ms-xlargemargin-inline-start: var(--cx-space-xlarge);
.ms-2xlargemargin-inline-start: var(--cx-space-2xlarge);
.ms-3xlargemargin-inline-start: var(--cx-space-3xlarge);
.ms-4xlargemargin-inline-start: var(--cx-space-4xlarge);
.ms-5xlargemargin-inline-start: var(--cx-space-5xlarge);
.ms-6xlargemargin-inline-start: var(--cx-space-6xlarge);
.ms-0margin-inline-start: 0;
.ms-automargin-inline-start: auto;

Sass maps

Margin utilities are generated from Sass maps in scss/maps/_spacing.scss.

scss/maps/_spacing.scss
$spaces: (
  zero:           $space-zero,
  4xsmall:        $space-4xsmall,
  3xsmall:        $space-3xsmall,
  2xsmall:        $space-2xsmall,
  xsmall:         $space-xsmall,
  small:          $space-small,
  medium:         $space-medium,
  large:          $space-large,
  xlarge:         $space-xlarge,
  2xlarge:        $space-2xlarge,
  3xlarge:        $space-3xlarge,
  4xlarge:        $space-4xlarge,
  5xlarge:        $space-5xlarge,
  6xlarge:        $space-6xlarge,
);

Two maps are derived from $spaces in scss/utilities/_margin.scss:

  • $-margin-values — resolves each spacing key to its :root custom property via var(--space-*), plus 0 and auto
  • $-negative-margin-values — resolves each key to calc(-1 * var(--space-*)) for the negative scale
scss/utilities/_margin.scss
// Build a margin values map from $spaces. Each key maps to a spacing variable in addition to 0 and auto.
$-margin-values: map.merge(
  map-loop($spaces, varify, "$key", "space"),
  (0: 0, auto: auto)
);

// Build a negative margin values map from $spaces. Each key maps to a
// negative value of the corresponding spacing variable.
$-negative-margin-values: ();
@each $name, $value in $spaces {
  $-negative-margin-values: map.merge(
    $-negative-margin-values,
    ($name: #{calc(-1 * var(--space-#{$name}))})
  );
}

Design tokens

Spacing utilities consume design tokens from Chassis Tokens with the $cx- prefix. — See thedesign tokens page.

scss/tokens/_spacing.scss
$space-zero:          $cx-space-context-zero;
$space-4xsmall:       $cx-space-context-4xsmall;
$space-3xsmall:       $cx-space-context-3xsmall;
$space-2xsmall:       $cx-space-context-2xsmall;
$space-xsmall:        $cx-space-context-xsmall;
$space-small:         $cx-space-context-small;
$space-medium:        $cx-space-context-medium;
$space-large:         $cx-space-context-large;
$space-xlarge:        $cx-space-context-xlarge;
$space-2xlarge:       $cx-space-context-2xlarge;
$space-3xlarge:       $cx-space-context-3xlarge;
$space-4xlarge:       $cx-space-context-4xlarge;
$space-5xlarge:       $cx-space-context-5xlarge;
$space-6xlarge:       $cx-space-context-6xlarge;

Utilities API

Margin utilities are declared in scss/utilities/_margin.scss using the utilities API. The map includes both the positive scale and the negative scale.

scss/utilities/_margin.scss
"margin": (
  responsive: true,
  property: margin,
  class: m,
  values: $-margin-values
),
"margin-x": (
  responsive: true,
  property: margin-inline,
  class: mx,
  values: $-margin-values
),
"margin-y": (
  responsive: true,
  property: margin-block,
  class: my,
  values: $-margin-values
),
"margin-top": (
  responsive: true,
  property: margin-block-start,
  class: mt,
  values: $-margin-values
),
"margin-end": (
  responsive: true,
  property: margin-inline-end,
  class: me,
  values: $-margin-values
),
"margin-bottom": (
  responsive: true,
  property: margin-block-end,
  class: mb,
  values: $-margin-values
),
"margin-start": (
  responsive: true,
  property: margin-inline-start,
  class: ms,
  values: $-margin-values
),
// Negative margin utilities
"negative-margin": (
  responsive: true,
  property: margin,
  class: -m,
  enabled: $enable-negative-margins,
  values: $-negative-margin-values
),
"negative-margin-x": (
  responsive: true,
  property: margin-inline,
  class: -mx,
  enabled: $enable-negative-margins,
  values: $-negative-margin-values
),
"negative-margin-y": (
  responsive: true,
  property: margin-block,
  class: -my,
  enabled: $enable-negative-margins,
  values: $-negative-margin-values
),
"negative-margin-top": (
  responsive: true,
  property: margin-block-start,
  class: -mt,
  enabled: $enable-negative-margins,
  values: $-negative-margin-values
),
"negative-margin-end": (
  responsive: true,
  property: margin-inline-end,
  class: -me,
  enabled: $enable-negative-margins,
  values: $-negative-margin-values
),
"negative-margin-bottom": (
  responsive: true,
  property: margin-block-end,
  class: -mb,
  enabled: $enable-negative-margins,
  values: $-negative-margin-values
),
"negative-margin-start": (
  responsive: true,
  property: margin-inline-start,
  class: -ms,
  enabled: $enable-negative-margins,
  values: $-negative-margin-values
)