Skip to main content

Utilities

Spacing

A wide range of shorthand responsive margin, padding and gap utilities on the theme's 0–8, 4 px scale.

The scale

This theme's spacing scale is not stock Bootstrap's. Stock Bootstrap has six steps (0–5) where step 3 is 1 rem. rb-bootstrap has nine steps (0–8) on a 4 px base where step 4 is 1 rem. The scale mirrors the --space-0 … --space-8 design tokens exactly. If you are porting markup from stock Bootstrap, see Migrating — every .m-3 and .p-5 needs a second look.

Step rb-bootstrap Token Stock Bootstrap 5.3
00--space-00
1.25 rem (4 px)--space-1.25 rem (4 px)
2.5 rem (8 px)--space-2.5 rem (8 px)
3.75 rem (12 px)--space-31 rem (16 px)
41 rem (16 px)--space-41.5 rem (24 px)
51.5 rem (24 px)--space-53 rem (48 px)
62 rem (32 px)--space-6—
73 rem (48 px)--space-7—
84 rem (64 px)--space-8—
Quick translation from stock: 3 → 4, 4 → 5, 5 → 7. Steps 1 and 2 are unchanged.

Every step, drawn to size. The number in each box is its .p-* class; the box grows by the padding on all sides.

0
1
2
3
4
5
6
7
8
HTML
<div class="bg-body-tertiary border"><div class="p-0 text-bg-navy text-center fs-6" style="min-width: 2rem">0</div></div>
<div class="bg-body-tertiary border p-1"><div class="text-bg-navy text-center fs-6" style="min-width: 2rem">1</div></div>
<div class="bg-body-tertiary border p-2"><div class="text-bg-navy text-center fs-6" style="min-width: 2rem">2</div></div>
<div class="bg-body-tertiary border p-3"><div class="text-bg-navy text-center fs-6" style="min-width: 2rem">3</div></div>
<div class="bg-body-tertiary border p-4"><div class="text-bg-navy text-center fs-6" style="min-width: 2rem">4</div></div>
<div class="bg-body-tertiary border p-5"><div class="text-bg-navy text-center fs-6" style="min-width: 2rem">5</div></div>
<div class="bg-body-tertiary border p-6"><div class="text-bg-navy text-center fs-6" style="min-width: 2rem">6</div></div>
<div class="bg-body-tertiary border p-7"><div class="text-bg-navy text-center fs-6" style="min-width: 2rem">7</div></div>
<div class="bg-body-tertiary border p-8"><div class="text-bg-navy text-center fs-6" style="min-width: 2rem">8</div></div>

Margin and padding

Assign responsive-friendly margin or padding values to an element or a subset of its sides with shorthand classes. Includes support for individual properties, all properties, and vertical and horizontal properties. Classes are built from the nine-step spacing map above.

Using the CSS Grid layout module? Consider using the gap utility instead.

Notation

Spacing utilities that apply to all breakpoints, from xs to xxl, have no breakpoint abbreviation in them. This is because those classes are applied from min-width: 0 and up, and thus are not bound by a media query. The remaining breakpoints, however, do include a breakpoint abbreviation.

The classes are named using the format {property}{sides}-{size} for xs and {property}{sides}-{breakpoint}-{size} for sm, md, lg, xl, and xxl.

Where property is one of:

  • m — for classes that set margin
  • p — for classes that set padding

Where sides is one of:

  • t — for classes that set margin-top or padding-top
  • b — for classes that set margin-bottom or padding-bottom
  • s — (start) for classes that set margin-left or padding-left in LTR, margin-right or padding-right in RTL
  • e — (end) for classes that set margin-right or padding-right in LTR, margin-left or padding-left in RTL
  • x — for classes that set both *-left and *-right
  • y — for classes that set both *-top and *-bottom
  • blank — for classes that set a margin or padding on all 4 sides of the element

Where size is one of:

  • 0 — eliminates the margin or padding by setting it to 0
  • 1 — .25rem (4 px)
  • 2 — .5rem (8 px)
  • 3 — .75rem (12 px)
  • 4 — 1rem (16 px)
  • 5 — 1.5rem (24 px)
  • 6 — 2rem (32 px)
  • 7 — 3rem (48 px)
  • 8 — 4rem (64 px)
  • auto — for classes that set the margin to auto (margin only)

(You can add more sizes by adding entries to the $spacers Sass map variable.)

Examples

Here are some representative examples of these classes:

.mt-0 {
  margin-top: 0 !important;
}

.ms-4 {
  margin-left: 1rem !important;
}

.px-2 {
  padding-left: .5rem !important;
  padding-right: .5rem !important;
}

.p-7 {
  padding: 3rem !important;
}

Live, with the measurement written in each box. The tinted outer box is the padded element; the navy block is its content.

.p-2 = 8 px
.p-4 = 16 px
.px-6 .py-2 = 32 px / 8 px
.pt-8 = 64 px above
HTML
<div class="p-2 bg-body-tertiary border"><div class="text-bg-navy px-2">.p-2 = 8 px</div></div>
<div class="p-4 bg-body-tertiary border"><div class="text-bg-navy px-2">.p-4 = 16 px</div></div>
<div class="px-6 py-2 bg-body-tertiary border"><div class="text-bg-navy px-2">.px-6 .py-2 = 32 px / 8 px</div></div>
<div class="pt-8 bg-body-tertiary border"><div class="text-bg-navy px-2">.pt-8 = 64 px above</div></div>

Margins are the gap outside the border. The dotted preview background shows the offset.

.m-5 = 24 px on all sides
.mt-8 .mb-1 .mx-2
HTML
<div class="bg-body-tertiary border d-inline-block">
  <div class="m-5 text-bg-navy px-2 py-1">.m-5 = 24 px on all sides</div>
</div>
<div class="bg-body-tertiary border d-inline-block ms-4">
  <div class="mt-8 mb-1 mx-2 text-bg-navy px-2 py-1">.mt-8 .mb-1 .mx-2</div>
</div>

Horizontal centering

Additionally, Bootstrap also includes an .mx-auto class for horizontally centering fixed-width block level content — that is, content that has display: block and a width set — by setting the horizontal margins to auto.

Centered element
HTML
<div class="mx-auto p-2 text-bg-navy" style="width: 200px;">
  Centered element
</div>

Negative margin

In CSS, margin properties can utilize negative values (padding cannot). Stock Bootstrap turns negative margin utilities off; this theme turns them on ($enable-negative-margins: true), so .m-n1 … .m-n8 and every side and breakpoint variant exist. The syntax is nearly the same as the default, positive margin utilities, but with the addition of n before the requested size.

Here's an example class that's the opposite of .mt-1:

.mt-n1 {
  margin-top: -.25rem !important;
}

The classic use: pull a badge or a figure up over the element above it, or cancel a parent's padding so a full-bleed strip runs edge to edge.

A padded card body (.p-4).

.mx-n4 — a full-bleed strip that cancels the card padding

Back inside the padding.

HTML
<div class="p-4 bg-body-tertiary border">
  <p class="mb-4">A padded card body (<code>.p-4</code>).</p>
  <div class="mx-n4 p-2 text-bg-navy text-center">.mx-n4 — a full-bleed strip that cancels the card padding</div>
  <p class="mt-4 mb-0">Back inside the padding.</p>
</div>
.mt-n6 pulls this badge 32 px up, over the border
HTML
<div class="bg-body-tertiary border p-4 mt-5">
  <span class="badge text-bg-gold mt-n6 d-inline-block">.mt-n6 pulls this badge 32 px up, over the border</span>
</div>

All negative steps, for every side and breakpoint:

  • .m-n1 … .m-n8
  • .mt-n1 … .mt-n8, .mb-n*, .ms-n*, .me-n*, .mx-n*, .my-n*
  • .m-{sm|md|lg|xl|xxl}-n1 … -n8, and the same for every side

Gap

When using display: grid or display: flex, you can make use of gap utilities on the parent element. This can save on having to add margin utilities to individual children of the grid or flex container. Gap utilities are responsive by default, and are generated via our utilities API, based on the $spacers Sass map — so they run 0–8 too.

Grid item 1
Grid item 2
Grid item 3
Grid item 4
HTML
<div class="grid gap-4 text-center">
  <div class="p-2 g-col-6 bg-body-tertiary border">Grid item 1</div>
  <div class="p-2 g-col-6 bg-body-tertiary border">Grid item 2</div>
  <div class="p-2 g-col-6 bg-body-tertiary border">Grid item 3</div>
  <div class="p-2 g-col-6 bg-body-tertiary border">Grid item 4</div>
</div>

Support includes responsive options for all of Bootstrap's grid breakpoints, as well as nine sizes from the $spacers map (0–8). There is no .gap-auto utility class as it's effectively the same as .gap-0.

The scale, side by side (each strip is a flex row with the named gap):

gap-14 px·
gap-28 px·
gap-312 px·
gap-416 px·
gap-524 px·
gap-632 px·
gap-748 px·
gap-864 px·
HTML
<div class="d-flex gap-1 mb-2"><span class="text-bg-navy px-2">gap-1</span><span class="text-bg-navy px-2">4 px</span><span class="text-bg-navy px-2">·</span></div>
<div class="d-flex gap-2 mb-2"><span class="text-bg-navy px-2">gap-2</span><span class="text-bg-navy px-2">8 px</span><span class="text-bg-navy px-2">·</span></div>
<div class="d-flex gap-3 mb-2"><span class="text-bg-navy px-2">gap-3</span><span class="text-bg-navy px-2">12 px</span><span class="text-bg-navy px-2">·</span></div>
<div class="d-flex gap-4 mb-2"><span class="text-bg-navy px-2">gap-4</span><span class="text-bg-navy px-2">16 px</span><span class="text-bg-navy px-2">·</span></div>
<div class="d-flex gap-5 mb-2"><span class="text-bg-navy px-2">gap-5</span><span class="text-bg-navy px-2">24 px</span><span class="text-bg-navy px-2">·</span></div>
<div class="d-flex gap-6 mb-2"><span class="text-bg-navy px-2">gap-6</span><span class="text-bg-navy px-2">32 px</span><span class="text-bg-navy px-2">·</span></div>
<div class="d-flex gap-7 mb-2"><span class="text-bg-navy px-2">gap-7</span><span class="text-bg-navy px-2">48 px</span><span class="text-bg-navy px-2">·</span></div>
<div class="d-flex gap-8"><span class="text-bg-navy px-2">gap-8</span><span class="text-bg-navy px-2">64 px</span><span class="text-bg-navy px-2">·</span></div>

row-gap

row-gap sets the vertical space between children items in the specified container.

Grid item 1
Grid item 2
Grid item 3
Grid item 4
HTML
<div class="grid gap-0 row-gap-4 text-center">
  <div class="p-2 g-col-6 bg-body-tertiary border">Grid item 1</div>
  <div class="p-2 g-col-6 bg-body-tertiary border">Grid item 2</div>
  <div class="p-2 g-col-6 bg-body-tertiary border">Grid item 3</div>
  <div class="p-2 g-col-6 bg-body-tertiary border">Grid item 4</div>
</div>

column-gap

column-gap sets the horizontal space between children items in the specified container.

Grid item 1
Grid item 2
Grid item 3
Grid item 4
HTML
<div class="grid gap-0 column-gap-4 text-center">
  <div class="p-2 g-col-6 bg-body-tertiary border">Grid item 1</div>
  <div class="p-2 g-col-6 bg-body-tertiary border">Grid item 2</div>
  <div class="p-2 g-col-6 bg-body-tertiary border">Grid item 3</div>
  <div class="p-2 g-col-6 bg-body-tertiary border">Grid item 4</div>
</div>

Bootstrap's own grid uses gutters (.g-*, .gx-*, .gy-*) rather than gap; those also follow the 0–8 scale. The CSS-grid layout (.grid / .g-col-*) is documented on CSS grid.

CSS

Sass maps

Spacing utilities are declared via Sass map and then generated with our utilities API. The map lives in scss/_variables.scss and is re-emitted as --space-* custom properties by the token layer, so CSS written against the design tokens and markup written against the utilities always agree.

$spacer: 1rem;
$spacers: (
  0: 0,
  1: 0.25rem,
  2: 0.5rem,
  3: 0.75rem,
  4: 1rem,
  5: 1.5rem,
  6: 2rem,
  7: 3rem,
  8: 4rem,
);
$enable-negative-margins: true;

CSS variables

:root, [data-bs-theme="light"] {
  --space-0: 0;
  --space-1: 0.25rem;
  --space-2: 0.5rem;
  --space-3: 0.75rem;
  --space-4: 1rem;
  --space-5: 1.5rem;
  --space-6: 2rem;
  --space-7: 3rem;
  --space-8: 4rem;
}

Utilities API

Spacing utilities are declared in our utilities API in scss/_utilities.scss (Bootstrap's) and picked up by the extended map in the theme's own scss/_utilities.scss. See Utility API for how to add, remove or rename them.

"margin": (
  responsive: true,
  property: margin,
  class: m,
  values: map-merge($spacers, (auto: auto))
),
"negative-margin": (
  responsive: true,
  property: margin,
  class: m,
  values: $negative-spacers
),
"padding": (
  responsive: true,
  property: padding,
  class: p,
  values: $spacers
),
"gap": (
  responsive: true,
  property: gap,
  class: gap,
  values: $spacers
),
"row-gap": (
  responsive: true,
  property: row-gap,
  class: row-gap,
  values: $spacers
),
"column-gap": (
  responsive: true,
  property: column-gap,
  class: column-gap,
  values: $spacers
),