Web development
Arbitrary values: when to use them
Arbitrary values are the square-bracket classes such as w-[117px]. They solve one-off cases and quietly bypass the tokens of your theme.
Key points
- Square brackets cover values, properties and variants.
- A space inside the brackets is written as an underscore.
- The class must appear whole in the source, or it is never generated.
Arbitrary values in Tailwind CSS are the classes in square brackets, such as w-[117px]: they solve one isolated case, they do not replace a theme token.
Three forms, three jobs
| Form | Example | CSS generated |
|---|---|---|
| Arbitrary value | top-[117px] | top: 117px |
| Arbitrary property | [mask-type:luminance] | mask-type: luminance |
| Arbitrary variant | [&>*]:p-2 | > * { padding: 0.5rem } |
The value lives in the class, so it inherits variants and states: hover:top-[117px] and lg:top-[344px] work. An arbitrary property applies when Tailwind has no utility for that rule.
Spaces and variables
A space inside the brackets is written as _: grid-cols-[1fr_500px_2fr]. A real underscore needs a backslash escape.
Testo
The round-bracket syntax is the shorthand for var() added in Tailwind 4: bg-(--brand) means bg-[var(--brand)]. A length: or color: hint removes the ambiguity when the variable could be either.
The cost
Every arbitrary value leaves the scale: it is not in the theme, it does not change with a token, and a reviewer cannot check it. Ten scattered text-[13px] classes are ten separate decisions, and none of them shows up when you search for a variable.
The limitation
The class has to appear whole in the source: w-[${width}px] generates nothing, because the build reads text and does not run code. Strings assembled at runtime have to go, or be listed with @source inline(); in 4 safelist is gone.
Where to continue
The catalogue holds container components, tables and the pricing-01 block from shadcn/ui blocks. The framework is in what Tailwind CSS is, the maths in calc() and CSS variables; the comparison of approaches is Tailwind vs CSS Modules.
Frequently asked questions
When is an arbitrary value the right choice?
For an isolated case that will not become a rule, such as a position or a one-pixel fix. If the value repeats three times, it belongs in the theme as a token.
Do arbitrary values slow the build down?
Not measurably: the build generates one class per unique form. The cost sits in maintaining the markup, not in compiling it.
How do you write a space inside the square brackets?
With an underscore, as in grid-cols-[1fr_500px_2fr]. Tailwind turns it into a space; a literal underscore takes a backslash in front.
What is the difference between bg-[--brand] and bg-(--brand)?
bg-(--brand) is the Tailwind 4 syntax and adds var() for you. The square-bracket form remains for fixed values, not for variables.
Why is an arbitrary class not generated?
Because the build reads the text of the source and does not run the code. A class assembled at runtime is not in the file, so Tailwind never sees it.