Custom Spacing Values

Tailwind's default spacing scale covers values from 0 to 96 (0 to 24rem in 0.25rem increments for small values, then larger steps). This scale is used consistently across margin, padding, width, height, gap, and positioning utilities. The values are designed to cover the vast majority of UI spacing needs, but real-world designs sometimes require values that fall between or beyond the defaults.

Design systems often require spacing values outside the default scale — a 128 value (32rem) for full-page hero sections, a 4.5 value (18px) for a specific element that sits between the standard 4 (16px) and 5 (20px), or a 13 value for a specific grid column width. Rather than using arbitrary values with bracket notation every time, add these values once to the config and give them a clean utility class name.

Add custom spacing values inside theme.extend.spacing. The key becomes the suffix in all spacing utilities, and the value is the CSS measurement you want. Use string keys for decimal or large numbers to ensure they are interpreted correctly. Once added, your custom spacing works automatically across m-*, p-*, w-*, h-*, gap-*, inset-*, and all other spacing utilities.

After adding custom spacing values, use them exactly like built-in spacing utilities. The key name goes after the utility prefix and hyphen. Custom spacing works with responsive prefixes, dark mode, and state variants just like defaults. The cross-utility nature means you write the config once and get padding, margin, width, height, and gap utilities from that single definition.

For projects with strict design systems that must use only specific spacing values, override the entire spacing scale by placing your values directly in theme.spacing (outside extend). This ensures no developer accidentally uses a spacing value outside your approved set. Be conservative with this approach — eliminating Tailwind's defaults removes many commonly needed utility classes.

Tailwind handles fractional keys like '4.5' by generating utility classes with a CSS-safe version of the decimal. The class name uses the fraction as written: p-4.5, m-4.5. For keys with slashes (like fractions for percentage-based spacing), the slash is encoded in the CSS selector. Always quote decimal and fraction keys as strings in the config object to prevent JavaScript from interpreting them as numeric literals.

Tailwind automatically generates negative variants for all spacing values, both default and custom. If you add '128': '32rem' to your spacing config, you also get -m-128, -mt-128, -inset-128, etc. Negative values are generated automatically — no separate config entry is needed. They are especially useful for overlapping elements, pull quotes, and decorative positioning.

Sometimes you want spacing values that scale with text size rather than being fixed rem values. Add spacing values using em units to the config — these will be relative to the element's own font size. For example, a button with px-1.5em padding would have proportional horizontal padding regardless of whether the button text is small or large.

When your design is based on an 8px grid system (or 4px base unit), map the entire grid to your spacing config. An 8px grid means all spacing is multiples of 8px: 8, 16, 24, 32, 40, 48, 64, 80, 96, 128. Tailwind's default spacing scale already aligns with this (1 unit = 4px, so 2 = 8px, 4 = 16px, 6 = 24px, 8 = 32px). You may only need to extend with values above 96.

When you need a one-off spacing value and do not want to pollute your config, use Tailwind's arbitrary value syntax with square brackets: p-[22px], w-[347px], mt-[3.75rem]. This generates the exact CSS value without adding to the config. Arbitrary values are ideal for one-time overrides but should not become a habit — if you use the same value three or more times, add it to the config instead.

As your custom spacing grows, document it alongside your color and typography tokens. Create a simple visual spacing reference in your Storybook, design system docs, or even a static HTML page that shows each spacing value as a colored block. This helps designers and developers use the right value from the config rather than reaching for arbitrary values or inconsistent one-offs.

Test your understanding of custom spacing values in Tailwind CSS.

In this lesson you learned: add custom spacing in theme.extend.spacing to extend the default scale without replacing it, custom spacing works automatically across all spacing utilities (padding, margin, width, height, gap), and arbitrary values with bracket notation are a good alternative for truly one-off measurements. Next up we explore CSS custom properties as design tokens in Tailwind.