Gap

Overview

Gap utilities apply the CSS gap, row-gap, and column-gap properties to flex and grid containers, distributing space between items without adding margin to individual children. All three utilities are responsive and share the same $spaces spacing scale used by margin and padding.

Notation

Gap 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 {property}-{size} for xs and {breakpoint}:{property}-{size} for sm, md, lg, xl, and 2xl.

Where property is one of:

• gap — sets gap (both row and column gap simultaneously)
• row-gap — sets row-gap
• column-gap — sets column-gap

Where size is one of:

• zero or 0 — eliminates the gap by setting it to 0
• 4xs — default token value is 0.0625rem (1px).
• 3xs — default token value is 0.125rem (2px).
• 2xs — default token value is 0.25rem (4px).
• xs — default token value is 0.5rem (8px).
• md — default token value is 1rem (16px).
• lg — default token value is 1.25rem (20px).
• xl — default token value is 1.5rem (24px).
• 2xl — default token value is 1.75rem (28px).
• 3xl — default token value is 2rem (32px).
• 4xl — default token value is 2.25rem (36px).
• 5xl — default token value is 2.5rem (40px).
• 6xl — default token value is 3rem (48px).

There is no .gap-auto class — auto has no defined behavior for gap in the CSS specification.

gap

.gap-{size} sets gap on a flex or grid container, controlling spacing between all items in both directions at once.

<div class="grid gap-md">
  <div class="g-col-6 p-xs">Item 1</div>
  <div class="g-col-6 p-xs">Item 2</div>
  <div class="g-col-6 p-xs">Item 3</div>
  <div class="g-col-6 p-xs">Item 4</div>
</div>

row-gap

.row-gap-{size} controls vertical spacing between rows in a grid or flex container without affecting column spacing.

<div class="grid gap-0 row-gap-md">
  <div class="g-col-6 p-xs">Item 1</div>
  <div class="g-col-6 p-xs">Item 2</div>
  <div class="g-col-6 p-xs">Item 3</div>
  <div class="g-col-6 p-xs">Item 4</div>
</div>

column-gap

.column-gap-{size} controls horizontal spacing between columns in a grid or flex container without affecting row spacing.

<div class="grid gap-0 column-gap-md">
  <div class="g-col-6 p-xs">Item 1</div>
  <div class="g-col-6 p-xs">Item 2</div>
  <div class="g-col-6 p-xs">Item 3</div>
  <div class="g-col-6 p-xs">Item 4</div>
</div>

CSS

Gap utilities are generated via the utilities API in scss/utilities/_gap.scss.

Reference

Each class name, its CSS property, and the generated values appear in the reference table.

Sass maps

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

$spaces: (
  zero:           $space-zero,
  4xs:            $space-4xsmall,
  3xs:            $space-3xsmall,
  2xs:            $space-2xsmall,
  xs:             $space-xsmall,
  sm:             $space-small,
  md:             $space-medium,
  lg:             $space-large,
  xl:             $space-xlarge,
  2xl:            $space-2xlarge,
  3xl:            $space-3xlarge,
  4xl:            $space-4xlarge,
  5xl:            $space-5xlarge,
  6xl:            $space-6xlarge,
);

$-gap-values is derived from $spaces in scss/utilities/_gap.scss, resolving each spacing key to its :root custom property via var(--space-*), plus 0.

// Build a gap values map from $spaces. Each key maps to its :root spacing variable, plus 0.
$-gap-values: map.merge(map-loop($spaces, varify, "$key", "space"), (0: 0));

Utilities API

Gap utilities are declared in scss/utilities/_gap.scss using the utilities API.

"gap": (
  responsive: true,
  property: gap,
  class: gap,
  values: $-gap-values
),
"row-gap": (
  responsive: true,
  property: row-gap,
  class: row-gap,
  values: $-gap-values
),
"column-gap": (
  responsive: true,
  property: column-gap,
  class: column-gap,
  values: $-gap-values
),