repeating-radial-gradient()

The repeating-radial-gradient() function is used to create a repeating <gradient>. A <gradient> is an <image> that is made of two ore more colors that smoothly fade from one color to another.

The repeating-radial-gradient() function has the same syntax and takes the same values as its non-repeating sibling, the radial-gradient() function. Please refer to the radial-gradient() entry for more about creating a radial gradient. This entry will focus on the repeatability of the gradient.

There is one main difference between repeating-radial-gradient() and radial-gradient(): The radial-gradient()‘s color stops are spread along the gradient ray so that the gradient is automatically spread to fill the entire gradient box, for example, the background painting area of the element if it is used as a background image on an element. The repeating-radial-gradient(), on the other hand, automatically repeats the color stops infinitely in both directions with their positions shifted by multiples of the difference between the last specified color-stop’s position and the first specified color-stop’s position. Let’s go through an example to better understand how this works.

We’ll start with a simple gradient created using radial-gradient(), and then turn it into a repeating-radial-gradient(). The following image shows the result of applying radial-gradient(circle, yellow, #009966, purple); to an element:

If we were to substitute the radial-gradient() function with the repeating-radial-gradient() function in the above example, we will still get the same result. That is because the function does not have any specified color stops, so the browser will just apply 0% for the first color, 100% for the third, and 50% for the second color, which is halfway through the first and third.

Let’s start by defining some color stops. We’ll start by defining a starting color stop and an ending one. We’ll let the browser position the second color between the starting and ending points as it normally would.

repeating-radial-gradient(circle, yellow 10px, #009966, purple 50px);
                

The result of applying the above repeating-radial-gradient() is:

The result we just got is identical to the one we got first, but instead of having the three colors spread along the gradient ray from 0% to 100%, we’re spreading them from 10px to 50px, which are the specified starting and ending stops, so it looks like the “big” gradient from before has become a “ring” in the repeating gradient. And the each “ring” is being repeated along the gradient ray.

At this point, if you’re familiar with how radial-gradient() works, you probably got an “ah-ha!” moment. In the radial-gradient() function, the last color stop defines where the last color begins, and then extends that color all the way to the 100% point of the gradient ray. So, using the same color stops with the radial-gradient() function, we’d get this:

Interesting, right? So what exactly happens in a repeating-radial-gradient()?

At this point, what we mentioned before should start to make more sense: When rendered, the color-stops in repeating-radial-gradient() are repeated infinitely in both directions, with their positions shifted by multiples of the difference between the last specified color-stop’s position and the first specified color-stop’s position.

So, in the above example, the difference between the last color-stop and the first one is 40px, so, repeating-radial-gradient(circle, yellow 10px, #009966, purple 50px) will be equivalent to radial-gradient(circle, ..., yellow -30px, #009966, purple 10px, yellow 10px, #009966, purple 50px, yellow 50px, #009966, purple 90px, ...). Note that the last color-stop and first color-stop will always coincide at the boundaries of each group (or “ring”), which will produce sharp transitions if the gradient does not start and end with the same color. (Notice the sharp edges between yellow and purple where the repeating gradients meet.)

Every gradient “ring” in a repeating radial gradient behaves just like a normal radial gradient would. So, the following code:

repeating-radial-gradient(circle, yellow 10px, yellow 23.4px, #009966 23.4px, #009966 36.8px, purple 36.8px, purple 50px);
                

will create a striped background, where each radial gradient is a three-stripe gradient, repeated infinitely:

Trivia & Notes

If the distance between the first and last color-stops is zero (or rounds to zero due to implementation limitations), the browser should find the average color of a gradient with the same number and color of color-stops, but with the first and last color-stop an arbitrary non-zero distance apart, and the remaining color-stops equally spaced between them. Then it must render the gradient as a solid-color image equal to that average color.

If the distance between the first and last color-stops is non-zero, but is small enough that the browser knows that the physical resolution of the output device is insufficient to faithfully render the gradient, the browser should find the average color of the gradient and render the gradient as a solid-color image equal to the average color.

If the width of the ending shape of a repeating radial gradient is non-zero and the height is zero, or is close enough to zero that the browser knows that the physical resolution of the output device is insufficient to faithfully render the gradient, the browser must find the average color of the gradient and render the gradient as a solid-color image equal to the average color.

Note that, even though a gradient is made up of colors, it is not a <color> value, and therefore can’t be used as one.