tailwindcss

mirror of https://github.com/tailwindlabs/tailwindcss.git synced 2025-12-08 21:36:08 +00:00

Go to file

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]);
}
```

2025-01-08 16:04:28 +01:00

.github

use single quotes

2024-12-13 15:30:58 +01:00

crates

Apply Clippy suggestions (#15549 )

2025-01-06 11:59:31 +01:00

integrations

Upgrade: Do not extract class names from functions (#15566 )

2025-01-07 15:31:48 +01:00

packages

Add functional utility syntax (#15455 )