tailwind-syntax-arbitrary-values

name	tailwind-syntax-arbitrary-values
description	Use when needing a one-off value that is not in the theme: specific hex colors, arbitrary pixel sizes, calc() expressions, custom grid templates, unusual font sizes, specific transforms, custom selectors, runtime CSS-variable values. Use also when reading existing Tailwind markup and encountering `bg-[#1da1f2]`, `w-[calc(100%-2rem)]`, `data-[state=open]:`, `[mask-type:luminance]`, `bg-(--brand)`, `[&_p]:`, or any other square-bracket / parens-bracket utility, and needing to know what it compiles to. Use also when an arbitrary value is being misinterpreted (background-size vs background-position, font-size vs color) and a type hint is required. Prevents (a) reaching for arbitrary syntax when a theme token already exists (lazy arbitrary values fragment design systems), (b) dynamic class-string concatenation like `bg-[${color}]` that never appears as a literal token and silently generates no CSS, (c) using v4 parens CSS-var syntax `bg-(--brand)` in a v3 project where it is parsed incorrectly, (d) using literal spaces inside `[...]` which terminates the class-name token, (e) mistaking a type-hint prefix as the property name itself (`text-[color:var(--c)]` is a `color` utility, not a property assignment), and (f) reaching for `text-[14.5px]` when `text-base/[1.4]` size-plus-line-height syntax fits, or `mt-17` in v4 where dynamic integer spacing avoids arbitrary syntax entirely. Covers the complete arbitrary-value system: value-arbitrary `bg-[#hex]`, `w-[calc()]`, `text-[Npx]`, `top-[-Npx]`, modifier-arbitrary `[&:nth-child(3)]:`, `[&>*]:`, `[&_p]:`, variant-arbitrary `data-[state=open]:`, `aria-[expanded=true]:`, `supports-[display:grid]:`, arbitrary-property `[mask-type:luminance]`, `[scroll-snap-stop:always]`, type-hint disambiguation `bg-[length:200px_100px]`, `bg-[image:url(...)]`, `text-[color:var(--c)]`, `text-[length:var(--c)]`, CSS-variable shorthand `bg-(--brand)` (v4 parens) vs `bg-[var(--brand)]` (v3 brackets), space encoding with `_`, comma encoding with `_` in v4 (`grid-cols-[max-content_1fr]`), source-detection rules (classes must be literal whole tokens), JIT performance model (v3 JIT vs v4 Oxide), and the v4 dynamic-integer fallback for spacing that obviates many arbitrary use cases. Keywords: arbitrary value, arbitrary class, brackets syntax, bracket notation, one-off color, bg-[hex], w-[calc], text-[px], custom value, custom selector, arbitrary variant, arbitrary modifier, arbitrary property, [mask-type], data-[state], aria-[expanded], type hint, length color image, bg-[length:], text-[color:], CSS variable Tailwind, bg-(--var), v4 parens syntax, bg-[var()], v3 brackets, underscore space, why does my arbitrary class not work, dynamic class not generated, JIT compiler, just in time, Oxide engine, performance, literal token, class detection, source scanning, mt-17, dynamic spacing.
license	MIT
compatibility	Designed for Claude Code. Requires Tailwind CSS v3.4 or v4.0+.
metadata	{"author":"OpenAEC-Foundation","version":"1.0"}

Tailwind CSS Syntax: Arbitrary Values

Arbitrary values are Tailwind's escape hatch: any utility can accept a one-off value via square-bracket syntax (or parens for CSS variables in v4). The syntax is identical in v3 and v4 ; the only difference is the v4 parens shorthand for CSS variables and the v4 Oxide engine that generates the CSS roughly 5x faster. Mastering arbitrary values means knowing WHEN to reach for them (rarely) and WHEN to use a theme token (almost always).

Quick Reference

Five arbitrary-value patterns

Pattern : example : compiles to
Value-arbitrary : bg-[#1da1f2] : background-color: #1da1f2
Modifier-arbitrary : [&:nth-child(3)]:underline : custom selector wraps the utility
Variant-arbitrary : data-[state=open]:rotate-180 : [data-state="open"] { rotate: 180deg }
Arbitrary property : [mask-type:luminance] : mask-type: luminance (no utility namespace at all)
Type-hinted arbitrary : bg-[length:200px_100px] : disambiguates ambiguous values

Top 3 most-used patterns

<!-- 1. One-off color or size (works v3 + v4) -->
<button class="bg-[#1da1f2] text-[14.5px] w-[calc(100%-2rem)]">Custom values</button>

<!-- 2. CSS variable for runtime theming -->
<!-- v4 parens shorthand -->
<div class="bg-(--brand-bg) text-(--brand-fg)">v4</div>
<!-- v3 brackets equivalent -->
<div class="bg-[var(--brand-bg)] text-[var(--brand-fg)]">v3</div>

<!-- 3. Arbitrary variant for one-off selector -->
< =>
  First (bold)
  Second