CSS radial-gradient() Function

The radial-gradient() function allows you to create a radial gradient using CSS.

CSS gradients allow you to apply multiple background colors to an element that blend from one color to the next. Like this:

To create a radial gradient, use the radial-gradient() function as a value to any property that accepts images (for example, background-image, background, or border-image properties). CSS gradients use these properties to build an image of the specified gradient.

Radial gradients have a circular or elliptical shape. This is in contrast to linear gradients which run in a straight line.

Radial gradients emerge from a single point and smoothly spread outward in a circular or elliptical shape.

When creating a radial gradient, you indicate the center of the gradient, as well as the size and shape (of the ending shape). You also provide a list of color stops, starting from the center and progressing out. Color stops specify which colors go where in the gradient.

Setting the Shape

You can choose between circle and ellipse when creating radial gradients.

In the previous example, I didn't specify a shape, so the gradient defaulted to an ellipse.

Ellipse

Here's an example that uses ellipse:

Circle

Here's an example that uses circle:

Gradient Position

You have the option of specifying the position of the gradient's center. If you don't specify this it will default to the center.

You can use a length value to define the position (e.g. 10px), a percentage value (e.g. 10%), or one of the positioning keywords such as left, top, etc. You an also use a valid combination of these keywords such as top left, top right.

Color Stops

Color stops are the bit that tell the gradient which colors to use and where. You specify the color to use and (optionally) the position along the gradient line that it should be located at.

Three Color Stops

The previous examples use two color stops — for the start color and the end color.

In this example we add a third color. Because we don't specify a position for any of the colors, they use the default position and spread evenly across the gradient:

Positioning the Color Stops

You can specify where each color is located along the gradient line. With circles, you can use a length (e.g. 10px, 2em etc) to determine the position. With ellipses, you can use a length or percentage value.

Here's a similar example to the previous one, except, in this one we specify a position for each color stop:

By specifying a position, you affect how much of each color is used. You can effectively "squash" one color into a smaller area and expand another if you wish.

Sharp Color Stops

You can even set your color stops so that they go straight from one specified color to the next (i.e. there's no gradual blend between colors). You can also have a mixture of sharp and soft transitions.

Like this:

Patterns with Gradients

You can take gradients to the next level and come up with some interesting patterns.

Here's an example:

Check out these CSS patterns if you're interested in this concept.

Official Syntax

The official syntax of the radial-gradient() function is as follows:

<radial-gradient> = radial-gradient(
  [ [ <shape> || <size> ] [ at <position> ]? , |
    at <position>, 
  ]?
  <color-stop> [ , <color-stop> ]+
)

Here's the syntax for color stops:

<color-stop> = <color> [ <percentage> | <length> ]?

And here's the syntax for the position:

<position> = [
  [ left | center | right | top | bottom | <length-percentage> ]
|
  [ left | center | right | <length-percentage> ]
  [ top | center | bottom | <length-percentage> ]
|
  [ center | [ left | right ] <length-percentage>? ] &&
  [ center | [ top | bottom ] <length-percentage>? ]
]

Possible Values

As indicated in the official syntax, the radial-gradient() function accepts the following values:

shape

Specifies the shape of the gradient. Can be either circle or ellipse.

The default value is circle if the <size> is a single length, and ellipse otherwise.

size
Specifies the size of the ending shape. The following values are valid:
closest-side
The ending shape is sized so that that it exactly meets the side of the gradient box closest to the gradient's center. If the shape is an ellipse, it exactly meets the closest side in each dimension.
farthest-side
Same as closest-side, except the ending shape is sized based on the farthest side(s).
closest-corner
The ending shape is sized so that that it passes through the corner of the gradient box closest to the gradient's center. If the shape is an ellipse, the ending shape is given the same aspect-ratio it would have if closest-side were specified.
farthest-corner

This is the default value.

Same as closest-corner, except the ending shape is sized based on the farthest corner. If the shape is an ellipse, the ending shape is given the same aspect ratio it would have if farthest-side were specified.

length (for circles)

Specifies the radius of the circle. Negative values are invalid.

Percentage values are not allowed on circles.

[length | percentage]{2} (for ellipses)

Specifies the radius of the ellipse. The first value represents the horizontal radius, the second the vertical radius. Percentages values are relative to the corresponding dimension of the gradient box. Negative values are invalid.

position

Specifies where the center of the gradient should be located. The following values are valid:

length
Gives a fixed length as the offset. For example, 10px 20px will position the gradient 10 pixels from the left and 20 pixels from the upper left corner of the background positioning area.
percentage
Specifies a percentage value as the offset.
top
Computes to 0% for the vertical position if one or two values are given, otherwise specifies the top edge as the origin for the next offset.
right
Computes to 100% for the horizontal position if one or two values are given, otherwise specifies the right edge as the origin for the next offset.
bottom
Computes to 100% for the vertical position if one or two values are given, otherwise specifies the bottom edge as the origin for the next offset.
left
Computes to 0% for the horizontal position if one or two values are given, otherwise specifies the left edge as the origin for the next offset.
center

This is the default value.

Computes to 50% (left 50%) for the horizontal position if the horizontal position is not otherwise specified, or 50% (top 50%) for the vertical position if it is.

color-stop
Valid values for color stops:
color
A valid color value.
percentage
A percentage value to define the placement of the color stop.
length
A length value to define the placement of the color stop.

CSS Specifications

Browser Support

The following table provided by Caniuse.com shows the level of browser support for this feature.