repeating-radial-gradient()

The repeating-radial-gradient() function creates a circular or elliptical color gradient starting from a center point and spreading outward. The gradient is then repeated infinitely. It’s mainly used with the background-image property because that’s what gradients are, images generated by the browser.

.element {
  background: repeating-radial-gradient(circle, crimson, purple 50px, crimson 100px);
}

The repeating-radial-gradient() function is defined in the CSS Images Module Level 3 and Level 4 specifications.

Check out the CSS Gradients Guide for a complete coverage on gradients.

Syntax

repeating-radial-gradient(<radial-shape> <rg-size> at <position> <color-interpolation-method>?, <color-stop-list>)

Arguments

/* Basic Gradients */
repeating-radial-gradient(purple, blue 50px, purple 100px);
repeating-radial-gradient(red 25% 50%, blue 50% 75%);
/* Radial Shapes */
repeating-radial-gradient(circle, yellow, orange 20px, yellow 60px);
repeating-radial-gradient(ellipse, white, purple 10%, white 20%);
/* Radial sizes */
repeating-radial-gradient(100px 200px, green, yellow 40px, green 80px);
repeating-radial-gradient(1px 2px, green, yellow 40px, green 80px);
/* Gradient positions */
repeating-radial-gradient(at right bottom, yellow, green 20px, yellow 40px);
repeating-radial-gradient(at 30px 10%, olive, green 100px, olive 200px);
/* Interpolation method */
repeating-radial-gradient(in oklab, #ff0, hsl(120 100 50) 50px, yellow 120px);
repeating-radial-gradient(in lch longer hue, yellow, blue 20px, yellow 50px);
/* All together */
repeating-radial-gradient(ellipse 24px 15px at left top in lch longer hue, yellow, oklch(0.87 0.14 99) 50px, yellow 100px);

The repeating-radial-gradient() function takes the same arguments as its non-repeating counterpart, radial-gradient(). And while the syntax is the same, some arguments are interpreted a little differently.

<color-interpolation-method>

This argument defines the color space used and the path taken between one color to another. To use it, we start with the in keyword followed by one of the many color spaces defined in CSS:

<color-interpolation-method> = in [ <rectangular-color-space> | <polar-color-space> <hue-interpolation-method>? ]
<rectangular-color-space> = srgb | srgb-linear | display-p3 | a98-rgb | prophoto-rgb | rec2020 | lab | oklab | xyz | xyz-d50 | xyz-d65
<polar-color-space> = hsl | hwb | lch | oklch

Note: It can be either written at the beginning of repeating-radial-gradient() or just before defining the <color-stop-list>.

If the color space uses polar coordinates (hsl, hwb, lch or oklch), then we can also define the path taken by the gradient using the <hue-interpolation-method> syntax:

<hue-interpolation-method> = [ shorter | longer | increasing | decreasing ] hue

<radial-shape>

This argument defines the gradient’s ending shape and can either be circle or ellipse.

If we don’t define it, then the ending shape will be an ellipse. Unless we provide a single <length> value for <radial-size>, then it will be a circle.

<radial-size>

In repeating-radial-gradient(), the <radial-size> refers to the size of the first repetition of the gradient, which then repeats infinitely, filling the whole gradient box.

Note: The gradient box refers to the area where the gradient is displayed. It’s usually the element’s border box, but it can be modified through the background-size property.

We can define the size explicitly, but it will depend on whether the ending shape is a circle or an ellipse:

• For circles, we can give it a single positive <length> to define its radius.
• For ellipses, we can give it a positive <length> to define its horizontal radius and a positive <length-percentage> to define its vertical radius.

Both circular and elliptical gradient sizes can be defined through a <radial-extent> keyword, which lets CSS extend the gradient up until a defined point:

• closest-side: The ending shape extends until the gradient box’s closest side to the gradient’s center.
• closest-corner: The ending shape extends until the gradient box’s closest corner to the gradient’s center.
• farthest-side: The ending shape extends until the gradient box’s farthest side to the gradient’s center.
• farthest-corner (default): The ending shape extends until the gradient box’s farthest corner to the gradient’s center.

<position>

This argument defines the center of the gradient using the <position> syntax for each axis. This includes explicit values like 40% 20% and 30px 100px, and physical values like left top, center, right bottom, etc. If omitted, it defaults to center. I’ve tried using logical property values and they do not seem to be supported, at least at the time I’m writing this.

<color-stop-list>

This argument defines the colors used and how far each is spaced out on the gradient, in a comma-separated list. Each color stop has a given <color> followed by optional <length-percentage> values:

• A single <color> lets CSS decide where to place it. If no positions are specified, then CSS places them evenly across the gradients, giving the same result as a radial-gradient().
• A <color> <length-percentage> argument defines where the given color should be found.
• Lastly, <color> <length-percentage> <length-percentage> defines a starting and ending point for the color to appear.

Basic usage

While it might appear complex at first glance, the repeating-radial-gradient() function uses same syntax as radial-gradient(). For example, we can make a simple repeating gradient using only two color stops:

.element {
  background: repeating-radial-gradient(red, yellow);
}

Tip: Remember that repeating-radial-gradient() returns an <image> type, meaning it’s used within the background-image (or background) property, but not inside background-color.

However, you’ll notice the “repeating” part of repeating-radial-gradient() is missing! And we are left with an everyday radial gradient. This is because we didn’t define the color stop positions, so CSS places each evenly on the gradient without visible repeats. To fix this, we can also define where each color should be found in the gradient:

.element {
  background: repeating-radial-gradient(red 50px, yellow 100px);
}

This time, we are saying red and yellow should be found 50px and 100px, respectively, away from the gradient’s center. Then that sequence is repeated infinitely, shifted in multiples of the difference between color stops. Since the difference between each is 50px, then it’s the same as writing it this way:

radial-gradient(red 0px, yellow 50px, red 50px, yellow 100px, red 100px, yellow 150px, ...)

Since each repetition always matches the boundary of the next one, you’ll notice there is an abrupt transition between them. To avoid this, the repeating gradient must start and end on the same color:

.element {
  background: repeating-radial-gradient(yellow, red 50px, yellow 100px);
}

We can also use percentage values, which keep the number of repetitions in the gradient constant, regardless of the background size:

.element {
  background: repeating-radial-gradient(yellow, red 25%, yellow 50%);
}

Note: Here, percentage values (like 60%) are relative to the gradient’s radius. While lengths (like 50px) refer to the distance going right from the gradient’s center.

Same as radial-gradient()

We only have to be careful when writing color stops on repeating radial gradients, but everything else is the same as in regular radial gradients. For example, we can choose the gradient’s shape to be either a circle or the default ellipse:

/* Circular gradient */
background: repeating-radial-gradient(circle, /* color stops */);
/* Elliptical gradient */
background: repeating-radial-gradient(ellipse, /* color stops */);

We can also move around the gradient’s center by defining its horizontal and vertical position after the at keyword and using the <position> syntax, relative to the gradient’s box top-left corner. These include:

• Physical values (top right)
• Lengths (20px 60px)
• Percentages (40% 20%)
• Values outside the gradient box (-20px 110%).

/* Physical value */
background: repeating-radial-gradient(circle 150px at top right, /* color stops */);
/* Lengths */
background: repeating-radial-gradient(circle 150px at 20px 60px, /* color stops */);
/* Percentages */
background: repeating-radial-gradient(circle 150px at 40% 20%, /* color stops */);
/* Negative and values above 100% */
background: repeating-radial-gradient(circle 150px at -20px 110%, /* color stops */);

Note: Logical property values, like start or block-end, don’t seem to work inside radial-gradient(), at least at the time of writing.

Full color stops

Similar to regular gradients, we can take advantage of the color stop syntax to get solid colors with a repeating gradient. To do this, we need each color to stop immediately after the next color begins, giving no space in between for the gradient to happen.

For example, the following gradient specifies black will go from 0px to 30px, and white will go from 30px to 100px immediately after that. This pattern is then repeated infinitely:

.element {
  /* Don’t forget the 0px! */
  background: repeating-radial-gradient(circle, black 0px 30px, white 30px 100px);
}

Unlike regular radial gradients, the initial 0px for the starting color is necessary for the repetition to succeed.

Specification

The repeating-radial-gradient() function is defined in the CSS Images Module Level 3 and Level 4 specifications, which are currently in Editor’s Draft. The color interpolation methods are defined in the CSS Color Module Level 4.

Browser support

Both the repeating-radial-gradient() base and interpolation method syntaxes are supported across all browsers.

More information

• CSS Gradients Guide (CSS-Tricks)
• Do you really understand CSS radial-gradients? (Patrick Brosset)
• A Deep CSS Dive Into Radial And Conic Gradients (Ahmad Shadeed)
• CSS Gradient Generator (CSS Gradient)

Related tricks!

Related