Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add radial and conic gradient utilities #14467

Merged
merged 2 commits into from
Sep 20, 2024

Conversation

adamwathan
Copy link
Member

This PR adds new bg-radial-* and bg-conic-* utilities for radial and conic gradients. It also adds support for "arbitrary gradients", where gradient utilities like bg-linear-*, bg-radial-*, and bg-conic-* can now accept a complete gradient definition as their arbitrary value.

Radial gradients

Radial gradients are created with the bg-radial utility, or the bg-radial-[…] utility, combined with the existing from-*, via-*, and to-* utilities.

The simple bg-radial utility just creates a radial gradient with no position information, which defaults to center:

radial-gradient({from}, {via}, {to});

If you use the arbitrary value format, whatever you provide as the arbitrary value is inserted into the first position:

radial-gradient({arbitrary value}, {from}, {via}, {to});

So a utility like bg-radial-[at_top_left] would produce this:

radial-gradient(at top left, {from}, {via}, {to});

This makes it possible to use some of the radial-gradient(…) features that this PR doesn't add first class support for, like using values like circle at center or providing a specific interpolation color space like in hsl longer hue. We may add explicit APIs for these in the future, but I'm proposing this PR first since those changes would be purely additive and none of the decisions here would create any conflict with those APIs.

Conic gradients

Conic gradients are created with the bg-conic, bg-conic-{bareNumber}, and bg-conic-[…] utilities, combined with the existing from-*, via-*, and to-* utilities.

The bg-conic utility creates a conic gradient with no angle, which defaults to 0deg:

conic-gradient({from}, {via}, {to});

The bg-conic-{bareNumber} utilities create conic gradients using the bare number as the angle:

conic-gradient(from {bareNumber}deg, {from}, {via}, {to});

The bg-conic-[…] arbitrary value utilities insert whatever you provide as the arbitrary value into the first position verbatim:

conic-gradient({arbitraryValue}, {from}, {via}, {to});

So a utility like bg-conic-[from_45deg_in_hsl] would produce this:

conic-gradient(from 45deg in hsl, {from}, {via}, {to});

Note that the from keyword needs to be provided by the user when using arbitrary values, but not when using bare values.

This makes it possible to use some of the conic-gradient(…) features that this PR doesn't add first class support for, like using values like at 0 0 or providing a specific interpolation color space like in hsl longer hue. We may add explicit APIs for these in the future, but I'm proposing this PR first since those changes would be purely additive and none of the decisions here would create any conflict with those APIs.

Arbitrary gradients

Prior to this PR, utilities like bg-linear-[…] could only accept positional information as their arbitrary value, like bg-linear-[to_top_right]. All of the color stops could only be provided using the from-*, via-*, and to-* utilities.

If you wanted to provide the complete gradient in one class, you needed to use bg-[…] and write out the gradient function yourself:

<div class="bg-[linear-gradient(to_right,var(--color-red-500),var(--color-yellow-400))]">

This PR refactors some things internally to make it possible to provide the entire gradient as the arbitrary value to each background gradient utility, like this:

<div class="bg-linear-[to_right,var(--color-red-500),var(--color-yellow-400)]">

This is nice if you're doing something very custom and you want to be able to look at the whole value together, while still avoiding some of the boilerplate you'd have if you had to write out the entire gradient function yourself.

@adamwathan adamwathan force-pushed the feat/radial-and-conic-gradients branch from 99ba042 to 0eeb4d3 Compare September 19, 2024 19:51
@adamwathan adamwathan force-pushed the feat/radial-and-conic-gradients branch from 0eeb4d3 to 82ae5ed Compare September 20, 2024 14:34
@adamwathan adamwathan merged commit bf115bf into next Sep 20, 2024
2 of 3 checks passed
@adamwathan adamwathan deleted the feat/radial-and-conic-gradients branch September 20, 2024 14:34
adamwathan added a commit that referenced this pull request Sep 20, 2024
This PR adds new `bg-radial-*` and `bg-conic-*` utilities for radial and
conic gradients. It also adds support for "arbitrary gradients", where
gradient utilities like `bg-linear-*`, `bg-radial-*`, and `bg-conic-*`
can now accept a complete gradient definition as their arbitrary value.

## Radial gradients

Radial gradients are created with the `bg-radial` utility, or the
`bg-radial-[…]` utility, combined with the existing `from-*`, `via-*`,
and `to-*` utilities.

The simple `bg-radial` utility just creates a radial gradient with no
position information, which defaults to `center`:

```
radial-gradient({from}, {via}, {to});
```

If you use the arbitrary value format, whatever you provide as the
arbitrary value is inserted into the first position:

```
radial-gradient({arbitrary value}, {from}, {via}, {to});
```

So a utility like `bg-radial-[at_top_left]` would produce this:

```
radial-gradient(at top left, {from}, {via}, {to});
```

This makes it possible to use some of the `radial-gradient(…)` features
that this PR doesn't add first class support for, like using values like
`circle at center` or providing a specific interpolation color space
like `in hsl longer hue`. We may add explicit APIs for these in the
future, but I'm proposing this PR first since those changes would be
purely additive and none of the decisions here would create any conflict
with those APIs.

## Conic gradients

Conic gradients are created with the `bg-conic`,
`bg-conic-{bareNumber}`, and `bg-conic-[…]` utilities, combined with the
existing `from-*`, `via-*`, and `to-*` utilities.

The `bg-conic` utility creates a conic gradient with no angle, which
defaults to `0deg`:

```
conic-gradient({from}, {via}, {to});
```

The `bg-conic-{bareNumber}` utilities create conic gradients using the
bare number as the angle:

```
conic-gradient(from {bareNumber}deg, {from}, {via}, {to});
```

The `bg-conic-[…]` arbitrary value utilities insert whatever you provide
as the arbitrary value into the first position verbatim:

```
conic-gradient({arbitraryValue}, {from}, {via}, {to});
```

So a utility like `bg-conic-[from_45deg_in_hsl]` would produce this:

```
conic-gradient(from 45deg in hsl, {from}, {via}, {to});
```

Note that the `from` keyword needs to be provided by the user when using
arbitrary values, but not when using bare values.

This makes it possible to use some of the `conic-gradient(…)` features
that this PR doesn't add first class support for, like using values like
`at 0 0` or providing a specific interpolation color space like `in hsl
longer hue`. We may add explicit APIs for these in the future, but I'm
proposing this PR first since those changes would be purely additive and
none of the decisions here would create any conflict with those APIs.

## Arbitrary gradients

Prior to this PR, utilities like `bg-linear-[…]` could only accept
positional information as their arbitrary value, like
`bg-linear-[to_top_right]`. All of the color stops could only be
provided using the `from-*`, `via-*`, and `to-*` utilities.

If you wanted to provide the complete gradient in one class, you needed
to use `bg-[…]` and write out the gradient function yourself:


```html
<div class="bg-[linear-gradient(to_right,var(--color-red-500),var(--color-yellow-400))]">
```

This PR refactors some things internally to make it possible to provide
the entire gradient as the arbitrary value to each background gradient
utility, like this:

```html
<div class="bg-linear-[to_right,var(--color-red-500),var(--color-yellow-400)]">
```

This is nice if you're doing something very custom and you want to be
able to look at the whole value together, while still avoiding some of
the boilerplate you'd have if you had to write out the entire gradient
function yourself.

---------

Co-authored-by: Adam Wathan <[email protected]>
philipp-spiess added a commit that referenced this pull request Sep 27, 2024
…*` (#14537)

In v4, we're making room for more gradient primitives with the addition
of [gradient and conic gradient
utilities](#14467). To
make this clearer, we are renaming all v3 `bg-gradient-*` utilities to
`bg-linear-*` to make it clear that these refer to linear gradients.

This PR adds a migration that will automatically update the class names
based on this migration.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants