Tailwind Custom Spacing

What Is Custom Spacing in Tailwind?

Tailwind's spacing theme key powers margin, padding, width, height, gap, and several other utility categories all at once. Extending it adds a new value that becomes available across every one of those utilities simultaneously.

This is different from using an arbitrary value like p-[22px] on a single element, extending the theme makes the new value reusable and consistent everywhere it's needed.

theme: {
  extend: {
    spacing: {
      18: "4.5rem",
      112: "28rem",
    },
  },
},

This instantly enables p-18, m-18, w-18, h-18, gap-18, and the same for 112, across every spacing-based utility.

Custom Spacing Configuration Syntax

theme.extend.spacing = {
  "{key}": "{value}",
};

• The key becomes the utility suffix, like 18 in p-18.
• The value is any valid CSS length, typically in rem to stay consistent with the rest of the scale.
• One new spacing key automatically applies to margin, padding, width, height, gap, inset, and more.
• Keys don't have to be numbers; you can use named keys like "gutter" for p-gutter.

Custom Spacing Cheatsheet

Patterns for extending the spacing scale for common layout needs.

Why Extend Instead of Using Arbitrary Values Everywhere

Arbitrary values like p-[22px] are great for one-off, truly unique cases, but repeating the exact same arbitrary value across many elements means the value lives nowhere centrally, making future design updates require a find-and-replace across your whole codebase.

<!-- Repeated arbitrary value, hard to update consistently later -->
<div class="p-[22px]">A</div>
<div class="p-[22px]">B</div>

<!-- Extended theme value, defined once, reused everywhere -->
<div class="p-18">A</div>
<div class="p-18">B</div>

Using calc() for Dynamic Spacing Values

Custom spacing values can use calc() to derive a value relative to other CSS, common for full-height sections that need to subtract a fixed navbar height.

theme: {
  extend: {
    spacing: {
      "screen-minus-nav": "calc(100vh - 4rem)",
    },
  },
},

<main class="h-screen-minus-nav overflow-y-auto">...</main>

Standardizing Section Spacing

Adding a named token like section for consistent vertical spacing between major page sections keeps large-scale layout rhythm consistent, even if the exact rem value doesn't match a "natural" step in the default scale.

theme: {
  extend: {
    spacing: {
      section: "6rem",
    },
  },
},

<section class="py-section">Section content</section>

Common Mistakes

• Repeating the same arbitrary spacing value across many elements instead of extending the theme once.
• Using raw pixel values in the config instead of rem, breaking consistency with the rest of the scale's relative sizing.
• Choosing numeric keys that don't fit Tailwind's existing step pattern, making the scale feel arbitrary and hard to remember.
• Forgetting that a new spacing key applies to many utility categories at once, potentially causing unexpected new utilities to appear (usually harmless, but worth knowing).
• Not restarting the dev server after adding new spacing keys, missing the newly available utilities.

Key Takeaways

• The spacing theme key powers margin, padding, width, height, gap, and more simultaneously.
• Extending spacing centralizes a value's definition instead of repeating arbitrary values everywhere.
• Spacing values can use calc() for dynamic, relative sizing needs.
• Named spacing tokens (like section or gutter) can improve readability over purely numeric keys.
• Prefer rem units in custom spacing values to stay consistent with Tailwind's existing scale.