custom-utilities/functional

9 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Functional utilities with --value() in @utility

Tailwind v4 supports functional (parametric) custom utilities via @utility with a wildcard name ending in -*, using the special --value() function to resolve the value. Example: @utility tab-* { tab-size: --value(--tab-size-*); } Combined with a @theme block defining --tab-size-2: 2; --tab-size-4: 4; --tab-size-github: 8; this matches utilities tab-2, tab-4, and tab-github, resolving against those theme keys.

Bare values in functional utilities

To resolve a functional utility's value as a bare (untyped) value, use --value({type}) where {type} is a CSS data type to validate against, e.g. @utility tab-* { tab-size: --value(integer); } matches tab-1, tab-76, etc. Available bare-value data types: number, integer, ratio, percentage.

Literal values in functional utilities

To support fixed literal string values in a functional @utility, use --value('literal') syntax with quotes, e.g. @utility tab-* { tab-size: --value("inherit", "initial", "unset"); } matches tab-inherit, tab-initial, tab-unset.

Arbitrary values in functional utilities

To support square-bracket arbitrary values in a functional @utility, use --value([{type}]) with square brackets, e.g. @utility tab-* { tab-size: --value([integer]); } matches tab-[1], tab-[76]. Available arbitrary-value data types: absolute-size, angle, bg-size, color, family-name, generic-name, image, integer, length, line-width, number, percentage, position, ratio, relative-size, url, vector, and * (any).

Combining theme, bare, and arbitrary value resolution in one utility

All three --value() forms (theme, bare-type, arbitrary) can appear as multiple declarations within the same @utility rule; declarations that fail to resolve are simply omitted from output. Example: @theme { --tab-size-github: 8; } @utility tab-* { tab-size: --value([integer]); tab-size: --value(integer); tab-size: --value(--tab-size-*); } This allows different handling per case, e.g. converting a bare integer to a percentage: @utility opacity-* { opacity: --value([percentage]); opacity: calc(--value(integer) * 1%); opacity: --value(--opacity-*); } --value() can also take multiple comma-separated arguments resolved left to right when the same treatment applies to all, e.g. tab-size: --value(--tab-size-*, integer, [integer]);

Default values for functional utilities with --default()

Use --default() inside --value() (or --modifier()) to provide a fallback when the utility is used without an explicit value/modifier. Example: @utility tab-* { tab-size: --value(integer, --default(4)); } This matches tab-2, tab-4, and bare tab (which uses default 4), compiling class .tab { tab-size: 4; } and .tab-2 { tab-size: 2; }. Similarly, --modifier(integer, --default(1)) provides a default modifier value; e.g. tab-2/3 gets line-height 3, while tab-2 alone gets line-height 1 (the default).

Negative value utilities via separate @utility rule

To support negative values for a functional utility in Tailwind v4, register the negative variant as a separate @utility with a leading dash in its name. Example: @utility inset-* { inset: --spacing(--value(integer)); inset: --value([percentage], [length]); } @utility -inset-* { inset: --spacing(--value(integer) * -1); inset: calc(--value([percentage], [length]) * -1); }

Modifiers in functional utilities via --modifier()

Modifiers (the part after a slash, e.g. text-lg/6) are handled with the --modifier() function, which works like --value() but operates on the modifier portion. Example: @utility text-* { font-size: --value(--text-*, [length]); line-height: --modifier(--leading-*, [length], [*]); } If no modifier is present, any declaration depending on --modifier() is simply omitted from the output.

Fraction values using the ratio data type

To support fraction-style values (like aspect ratios) in a functional @utility, use the CSS ratio data type with --value(); this signals Tailwind to treat the value and modifier as a single combined value rather than separate value/modifier. Example: @utility aspect-* { aspect-ratio: --value(--aspect-ratio-*, ratio, [ratio]); } This matches utilities like aspect-square, aspect-3/4, and aspect-[7/9].

Give your agent this brain