CSS repeating-radial-gradient() Function

The CSS repeating-radial-gradient() function allows you to create a radial gradient that repeats over and over again infinitely.

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

Repeating radial gradients are radial gradients where the color stops are repeated infinitely.

To create a repeating radial gradient, use the repeating-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. They emerge from a single point and smoothly spread outward in a circular or elliptical shape. This is in contrast to linear gradients which run in a straight line.

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.

When you do this, you're defining a single gradient. By using the repeating-radial-gradient() function, the gradient repeats outwards, over and over again.

Setting the Shape

You can choose between circle and ellipse when creating radial gradients. The same applies to repeating 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 to specify the position of the gradient's center. If you don't specify its position, 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 of each gradient iteration.

In this example we add a third color:

In this case we position the color in a way that "squashes" one color into a smaller area, while allowing the other color to expand into a larger area.

Try repositioning the color stops to see the effect it has on the appearance of the gradient.

Creating Smooth Transitions

The previous examples have sharp transitions between the end color of a gradient and the start color of the next gradient. You can soften this transition by using the same color for the start and end of the gradient. This creates more of a "blurred" effect between the colors.

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 repeating-radial-gradient() function uses the same syntax as the radial-gradient() function, which 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 repeating-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
A length value 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.