Handling One-Off Styles with Tailwind CSS Arbitrary Values

Solving the 'Magic Number' Dilemma

When building a UI, you will inevitably encounter a requirement that doesn't fit your predefined design tokens—such as a legacy image requiring a specific width of 342px or a brand color that isn't in your palette. Traditionally, this required adding a custom value to tailwind.config.js or writing a separate CSS file with a custom class.

The most efficient solution is Arbitrary Value support. By using square bracket notation (e.g., w-[342px]), you can generate a one-off utility class on the fly without polluting your global configuration. This keeps your theme file clean and your styles localized to the element that actually needs them.

How the JIT Engine Processes Arbitrary Values

Tailwind's Just-in-Time (JIT) engine does not ship a pre-built library of every possible pixel value. Instead, it uses a regex-based scanner to monitor your HTML and JavaScript files. When the scanner detects a pattern matching [value], it dynamically generates the corresponding CSS rule and injects it into the stylesheet.

Implementation Example

Consider a scenario where you need a grid layout with a complex minmax calculation and a specific hex color for a border. Instead of defining these in the config, apply them directly to the HTML:

<div class="grid grid-cols-[repeat(auto-fill,minmax(200px,1fr))] border-2 border-[#bada55] p-[17px]">
  <div class="bg-slate-100">Card 1</div>
  <div class="bg-slate-100">Card 2</div>
</div>

Key Configuration Rules

• No Spaces: The JIT scanner cannot parse spaces within square brackets. If a CSS function requires a space (like minmax or calc), replace the space with an underscore (_). The engine converts underscores back to spaces in the final CSS.
• Units Required: You must provide the unit (px, rem, %, vh). w-[10] is invalid; w-[10px] is valid.
• CSS Variables: You can reference CSS variables directly: bg-[var(--brand-primary)].

Critical Limitations and Common Pitfalls

The Dynamic String Trap

The most common failure point is attempting to use string interpolation to generate arbitrary values. Because the JIT engine scans your source code statically, it cannot execute JavaScript to determine what a class name will be at runtime.

Incorrect (Will not work):

<div class={`text-[${color}px]`}>Dynamic Text</div>

Correct: Use the style attribute for truly dynamic values, or map specific keys to full class strings:

const colorMap = { red: 'text-[12px]', blue: 'text-[14px]' };
<div class={colorMap[color]}>Static-mapped Text</div>

Design System Fragmentation

While arbitrary values are powerful, overusing them creates "design debt." If you find yourself using p-[17px] across multiple components, you are effectively creating a new design token without documenting it. In these cases, move the value into the theme.extend section of your tailwind.config.js to maintain a single source of truth.

Verification and Diagnostics

To verify that an arbitrary value is working correctly, follow these steps:

1. Apply the class to your element (e.g., top-[117px]).
2. Open the browser's Developer Tools (F12) and inspect the element.
3. Check the Styles pane. You should see a generated class like .top-\[117px\] { top: 117px; }.
4. If the class is present in the HTML but not in the Styles pane, check that the file containing the HTML is included in the content array of your tailwind.config.js.