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 xsmall and {breakpoint}:{property}-{size} for small, medium, large, xlarge, and 2xlarge.

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
• 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).

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-medium">
  <div class="g-col-6 p-xsmall">Item 1</div>
  <div class="g-col-6 p-xsmall">Item 2</div>
  <div class="g-col-6 p-xsmall">Item 3</div>
  <div class="g-col-6 p-xsmall">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-medium">
  <div class="g-col-6 p-xsmall">Item 1</div>
  <div class="g-col-6 p-xsmall">Item 2</div>
  <div class="g-col-6 p-xsmall">Item 3</div>
  <div class="g-col-6 p-xsmall">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-medium">
  <div class="g-col-6 p-xsmall">Item 1</div>
  <div class="g-col-6 p-xsmall">Item 2</div>
  <div class="g-col-6 p-xsmall">Item 3</div>
  <div class="g-col-6 p-xsmall">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,
  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,
);

$-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
),