Tailwind Arbitrary Values: Handling One-Off Sizes Without Config Bloat

A designer asks for a 117px top offset on a hero badge. Your Tailwind spacing scale jumps from 112px to 128px. Adding 117px to tailwind.config.js for a single use is config bloat. Arbitrary values let you write the exact value inline with square bracket notation and keep the theme clean.

The useful takeaway: use arbitrary values for genuine one-offs and rapid adjustments, and promote repeated values to named theme tokens.

The config bloat problem

Tailwind encourages a constrained design system through its theme. Spacing, colors, and sizing are defined in tailwind.config.js and exposed as utility classes. That works until a layout needs a value that does not exist in the scale.

The old options were to extend the theme for a single use, write custom CSS, or compromise the design. Extending the theme pollutes the global scale and makes future refactors harder. Arbitrary values avoid both by allowing top-[117px] or bg-[#bada55] directly in markup.

How arbitrary values work with JIT

Tailwind v3.0+ ships with a Just-in-Time engine. JIT scans your source files and generates only the classes it finds. Arbitrary values fit that model: the class name contains the CSS value inside brackets, and JIT emits a rule for that exact value on demand.

That means the final CSS bundle contains only the specific bracketed values you actually use, not an entire expanded scale. The syntax is utility-[value]. For values with spaces, Tailwind requires underscores, e.g. grid-cols-[1fr_500px_2fr].

Arbitrary values also support CSS variables for runtime theming: text-[var(--brand-color)]. The variable is resolved by the browser, so the class can stay static while the value changes at runtime.

Worked example: one-off offset and dynamic color

Consider a hero section that needs a precise offset and a brand color defined as a CSS variable.

<div class='relative'>
  <span class='absolute top-[117px] left-4 w-[342px] bg-[var(--brand-accent)] text-[var(--brand-color)] rounded-[12px]'>
    Limited offer
  </span>
</div>

top-[117px] applies a 117px top offset without adding 117 to the spacing scale. w-[342px] sets an exact width. bg-[var(--brand-accent)] and text-[var(--brand-color)] read values from CSS variables, useful when the brand palette is set at runtime.

To check the result in a Tailwind v3+ project, apply the class to an element and inspect it in browser dev tools. You can also inspect the generated CSS output to confirm JIT created a rule for the specific bracketed value. Attempting a space inside the brackets, such as top-[10 px], will not compile, which verifies the underscore rule.

Trade-offs and limits

Overuse fragments the design system. Scattered top-[117px], top-[119px], and top-[121px] across components make spacing inconsistent and hard to audit.

Readability drops with complex calculations inside brackets. w-[calc(100%-2rem)] is valid but harder to scan than a named token. Arbitrary values also do not participate in theme configuration, so they cannot be changed globally from tailwind.config.js.

A practical rule: use arbitrary values for prototyping, marketing exceptions, and values tied to external design files. When the same value appears three times or becomes a pattern, extract it to the theme as a named token.

Keep the theme as the source of truth and treat arbitrary values as an escape hatch, not a default.