mirror of
https://github.com/tailwindlabs/tailwindcss.git
synced 2025-12-08 21:36:08 +00:00
ee3add9d08
This PR adds support for functional utilities constructed via CSS.
# Registering functional utilities in CSS
To register a functional utility in CSS, use the `@utility potato-*`
syntax, where the `-*` signals that this is a functional utility:
```css
@utility tab-* {
tab-size: --value(--tab-size-*);
}
```
## Resolving values
The special `--value(…)` function is used to resolve the utility value.
### Resolving against `@theme` values
To resolve the value against a set of theme keys, use
`--value(--theme-key-*)`:
```css
@theme {
--tab-size-1: 1;
--tab-size-2: 2;
--tab-size-4: 4;
--tab-size-github: 8;
}
@utility tab-* {
/* tab-1, tab-2, tab-4, tab-github */
tab-size: --value(--tab-size-*);
}
```
### Bare values
To resolve the value as a bare value, use `--value({type})`, where
`{type}` is the data type you want to validate the bare value as:
```css
@utility tab-* {
/* tab-1, tab-76, tab-971 */
tab-size: --value(integer);
}
```
### Arbitrary values
To support arbitrary values, use `--value([{type}])` (notice the square
brackets) to tell Tailwind which types are supported as an arbitrary
value:
```css
@utility tab-* {
/* tab-[1], tab-[76], tab-[971] */
tab-size: --value([integer]);
}
```
### Supporting theme values, bare values, and arbitrary values together
All three forms of the `--value(…)` function can be used within a rule
as multiple declarations, and any declarations that fail to resolve will
be omitted in the output:
```css
@theme {
--tab-size-github: 8;
}
@utility tab-* {
tab-size: --value([integer]);
tab-size: --value(integer);
tab-size: --value(--tab-size-*);
}
```
This makes it possible to treat the value differently in each case if
necessary, for example translating a bare integer to a percentage:
```css
@utility opacity-* {
opacity: --value([percentage]);
opacity: calc(--value(integer) * 1%);
opacity: --value(--opacity-*);
}
```
The `--value(…)` function can also take multiple arguments and resolve
them left to right if you don't need to treat the return value
differently in different cases:
```css
@theme {
--tab-size-github: 8;
}
@utility tab-* {
tab-size: --value(--tab-size-*, integer, [integer]);
}
@utility opacity-* {
opacity: calc(--value(integer) * 1%);
opacity: --value(--opacity-*, [percentage]);
}
```
### Negative values
To support negative values, register separate positive and negative
utilities into separate declarations:
```css
@utility inset-* {
inset: calc(--var(--spacing) * --value([percentage], [length]));
}
@utility -inset-* {
inset: calc(--var(--spacing) * --value([percentage], [length]) * -1);
}
```
## Modifiers
Modifiers are handled using the `--modifier(…)` function which works
exactly like the `--value(…)` function but operates on a modifier if
present:
```css
@utility text-* {
font-size: --value(--font-size-*, [length]);
line-height: --modifier(--line-height-*, [length], [*]);
}
```
If a modifier isn't present, any declaration depending on a modifier is
just not included in the output.
## Fractions
To handle fractions, we rely on the CSS `ratio` data type. If this is
used with `--value(…)`, it's a signal to Tailwind to treat the value +
modifier as a single value:
```css
/* The CSS `ratio` type is our signal to treat the value + modifier as a fraction */
@utility aspect-* {
/* aspect-square, aspect-3/4, aspect-[7/9] */
aspect-ratio: --value(--aspect-ratio-*, ratio, [ratio]);
}
```