In Tailwind CSS v4, how do you apply a one-off value the theme lacks: a hex colour, a CSS variable, or an unsupported property?
answer
- an escape hatch inside the class name
- square brackets for a literal value
- parentheses for a CSS variable
- a bracketed property:value pair
- underscores for spaces; a data-type hint
basics
~10 sTailwind CSS v4 accepts arbitrary values in square brackets, such as bg-[#316ff6] or top-[117px]; a CSS variable uses parentheses, bg-(--promo); a property with no utility is written as [mask-type:luminance]. Spaces become underscores.
solid answer
~40 sFor a one-off, put the value in square brackets after the utility: `bg-[#316ff6]`, `top-[117px]`, `grid-cols-[1fr_500px_2fr]`, where underscores stand for spaces. To use a CSS variable, v4 has a shorthand in parentheses, `bg-(--promo)`, which means `bg-[var(--promo)]`; v3's `bg-[--promo]` form changed to this in v4. For a CSS property Tailwind has no utility for, write an arbitrary property: `[mask-type:luminance]`. When a variable is ambiguous, because `text-` can mean font size or colour, add a CSS data type: `text-(length:--hero-size)` or `text-(color:--accent)`. All of these combine with variants, for example `lg:top-[344px]`, and the full class string must appear in the source so the scanner generates it.
code
html · 5 lines<span class="bg-[#316ff6] px-2 text-white">Guest teacher</span>
<h1 class="text-(length:--hero-size) font-display">Morning flow</h1>
<section class="grid grid-cols-[1fr_500px_2fr] lg:top-[344px]">
<img class="[mask-type:luminance]" src="/instructors/ana.png" alt="">
</section>go deeper
Recall the square-bracket form for a literal value, the parentheses form for a CSS variable, and that underscores stand for spaces.
Explain arbitrary properties, type hints for ambiguous prefixes like text-, and the v3 to v4 changes to the variable shorthand and to commas.
Show the limits: the scanner needs the complete class, values built at runtime never compile, and repeated one-offs should be promoted to theme variables.
Decide how a codebase reviews arbitrary values, so the escape hatch stays a one-off tool and repeated values reach the theme.
## What an arbitrary value is Tailwind CSS v4 generates most utilities from theme variables: `bg-sage-600` exists because `--color-sage-600` is in `@theme`. Sometimes a value is needed once and does not deserve a token, such as a partner studio's brand blue on a single badge or a pixel offset that aligns a background image. **Arbitrary values** let the class name carry the value itself, and Tailwind generates the rule on the fly. ## The forms | Need | Syntax | Compiles roughly to | |---|---|---| | a literal value | `bg-[#316ff6]` | `background-color: #316ff6` | | a length | `top-[117px]` | `top: 117px` | | a CSS variable | `bg-(--promo)` | `background-color: var(--promo)` | | a property with no utility | `[mask-type:luminance]` | `mask-type: luminance` | | a theme value in a calculation | `rounded-[calc(var(--radius-xl)-1px)]` | `border-radius: calc(var(--radius-xl) - 1px)` | | an ambiguous variable | `text-(length:--hero-size)` | `font-size: var(--hero-size)` | Every form works with variants, so `lg:top-[344px]` and `hover:[mask-type:alpha]` behave like any other utility. An arbitrary property can also set a custom property under a condition: `[--scroll-offset:56px] lg:[--scroll-offset:44px]`. ## Variables: parentheses in v4 In v3, `bg-[--promo]` was a shorthand that added `var()` for you. Tailwind CSS v4 changed the syntax because, as the upgrade guide puts it, recent CSS made the bare form ambiguous. The v4 shorthand uses parentheses: - `bg-(--promo)` is shorthand for `bg-[var(--promo)]`. - The upgrade tool rewrites classes written in the old bracket form. ## Spaces, underscores and commas A class attribute is split on whitespace, so an arbitrary value cannot contain a literal space. The rules: 1. Write an underscore where a space belongs: `grid-cols-[1fr_500px_2fr]`. 2. Where a space would be invalid but underscores are common, such as inside `url()`, Tailwind keeps the underscore: `bg-[url('/what_a_rush.png')]`. 3. When an underscore is genuinely ambiguous, escape it: `before:content-['hello\_world']` (in JSX, use `String.raw` so the backslash survives). 4. Commas are not spaces. v3 turned commas into spaces in `grid-cols-*`, `grid-rows-*` and `object-*` for compatibility with v2; v4 dropped that, so `grid-cols-[max-content,auto]` must become `grid-cols-[max-content_auto]`. ## Type hints for ambiguous utilities Some utility prefixes map to more than one property. `text-` sets `font-size` or `color`; with a literal value Tailwind infers which (`text-[22px]` is a size, `text-[#bada55]` a colour). A variable gives no clue, so add a CSS data type before it: - `text-(length:--hero-size)` generates a font-size utility. - `text-(color:--accent)` generates a colour utility. ## Arbitrary value or inline style Both put a one-off value next to the markup, but they are not equivalent: | | Arbitrary value `top-[117px]` | Inline `style="top: 117px"` | |---|---|---| | Works with variants (`lg:`, `hover:`) | yes | no | | Lives in the generated stylesheet | yes | no, on the element | | Needs the class to be scanned | yes | no | | Value can change at runtime per element | only through a variable, `top-(--offset)` | yes | The last row is the useful one: when a value is computed at runtime, set a custom property inline (`style="--offset: 117px"`) and reference it with `top-(--offset)`, so the class string stays static. ## Limits worth stating in an interview - **The scanner reads class names as text.** `bg-[#316ff6]` must appear complete in a scanned file; assembling the bracket value at runtime produces nothing. - **An arbitrary value bypasses the theme.** Use one where a value is genuinely one-off; a value that repeats is a candidate for a theme variable, which also gives you `var(--color-…)` for custom CSS. - **Arbitrary variants are a separate feature.** Square brackets in the variant position, such as `[&:nth-child(3)]:`, modify the selector rather than the value. ## A short worked example On the class schedule, a guest-teacher badge uses a partner's colour once, a hero heading takes its size from a variable set by a layout component, and an instructor photo uses a mask property with no utility: ```html <span class="bg-[#316ff6] text-white">Guest teacher</span> <h1 class="text-(length:--hero-size)">Morning flow</h1> <img class="[mask-type:luminance]" src="/instructors/ana.png" alt=""> ``` Each class compiles to exactly one rule, and none of them requires a change to `@theme`.
- A class `text-(--hero-size)` produces a colour rule instead of a font size. Why, and what is the fix?`text-` maps to both `font-size` and `color`, and a variable carries no type Tailwind can infer, so the match is ambiguous. Add a CSS data type to the value: `text-(length:--hero-size)` for a size, `text-(color:--accent)` for a colour.
- When should a repeated arbitrary value become a theme variable instead?When the same literal shows up across components, declaring it in `@theme`, such as `--color-partner: #316ff6`, gives a named utility, a CSS variable for custom rules, and one place to change it. Arbitrary values are for genuinely one-off adjustments.
- bg-[--promo] still injects var() automatically in Tailwind CSS v4.
- A space inside square brackets works if the class is quoted.
- Commas inside grid-cols-[…] are converted to spaces in v4.
- Arbitrary values cannot be combined with hover: or lg:.
- A property with no utility requires writing a custom stylesheet rule.
- text-(--x) is always treated as a font size.
Assumes Tailwind CSS v4 (4.3.3 checked); v4 changed the variable shorthand from bg-[--var] to bg-(--var) and dropped v3's comma-to-space handling.