functional @utility

static @utility → functional @utility: the upgrade

A static @utility is one CSS rule for one fixed class. A functional @utility ends in -* and is a template: the * is a value slot, and the special --value() function resolves whatever you put there. This is exactly how every built-in utility (w-4, p-8, text-cyan-500) is authored internally — so your custom utilities inherit the full variant system (hover:, lg:, dark:) for free.

1 · tab-* — the canonical example (gold-check target)

This is the example from the official Tailwind docs. --value(integer) accepts any whole number; --default(4) makes the bare class tab resolve to tab-size: 4. The three <pre> blocks below have real tab characters — notice how the same source indent renders at different widths because the integer flows through --value().

def greet(name):
	return f"hi {name}"
		if cond:
			nested()

def greet(name):
	return f"hi {name}"
		if cond:
			nested()

def greet(name):
	return f"hi {name}"
		if cond:
			nested()

def greet(name):
	return f"hi {name}"
		if cond:
			nested()

The gold-check asserts tab-4 → tab-size: 4 and tab-8 → tab-size: 8. The second assertion is the important one: it proves the integer is actually read from the class and plumbed through --value(integer) — not a hardcoded fallback.

2 · text-shadow-* — integer plumbed into calc()

Functional utilities aren't limited to pass-through. Here the integer drives a calc() expression, building a glow scale from a single number. Gotcha: Tailwind v4.3 does ship a built-in text-shadow-* (preset scale: text-shadow-sm, text-shadow-lg…). Your custom @utility text-shadow-* adds the numeric branch (text-shadow-6) — the resolver picks the right branch per value. If you only need the presets, don't reinvent.

3 · grid-auto-fill-* — one utility, many declarations

A functional utility body can set multiple properties (just like the built-in line-clamp-*, which sets four). Here the integer becomes a minimum card width via minmax(), and the grid auto-fills as many cards as fit. Click a preset — the CDN's MutationObserver sees the class change and compiles the new rule on the fly.

the --value() resolver — every form

--value() is the bridge between the class suffix and your CSS. Stacking multiple --value() declarations (or comma-separated arguments) lets one utility accept theme keys, bare values, and arbitrary values — each branch that fails to resolve is silently dropped.

Heads-up: the older "--value(integer)? with a ? to make it optional" shorthand you may see in old blog posts does not exist in v4. The real mechanism is the --default() function.

when: functional @utility vs arbitrary value vs @theme

Three tools, three frequencies. Pick by how often the value recurs. See arbitrary values for the one-off escape hatch and arbitrary properties for one-off CSS properties Tailwind doesn't cover.

intent → pattern