CSS Reference Function

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:

circle-yellow-green-purple
radial-gradient(circle, yellow, #009966, purple);

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:

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

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:

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

In a radial-gradient() function, the last color stop defines where the last color begins, and then extends that color all the way to the end.

So, the purple color starts at 50px in this example, and is extended all the way to the 100% point of the gradient ray.

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:

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

Note that the color stops are calculated so that each color gets 1/3 of the distance, so they end up with equal widths.

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.

Official Syntax

<repeating-radial-gradient> = radial-gradient(
  [ [ circle               || <length> ]                          [ at <position> ]? , |
    [ ellipse              || [ <length> | <percentage> ]{2} ]    [ at <position> ]? , |
    [ [ circle | ellipse ] || <extent-keyword> ]                  [ at <position> ]? , |
    at <position> ,
  ]?
  <color-stop> [ , <color-stop> ]+
)

/* where.. */
<extent-keyword> = closest-corner | closest-side | farthest-corner | farthest-side

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

Values

<position>
A <position> that is resolved and works the same way the value of background-position does. If this value is not specified, it defaults to center.
<ending-shape>
Can be either circle or ellipse; determines whether the gradient’s ending shape is a circle or an ellipse, respectively. If <ending-shape> is omitted, the ending shape defaults to a circle if the <size> is a single <length>, and to an ellipse otherwise.
<size>
Determines the size of the gradient’s ending shape. If omitted it defaults to farthest-corner. It can be given explicitly or by keyword. For the purpose of the keyword definitions, consider the gradient box edges as extending infinitely in both directions, rather than being finite line segments.

If the ending-shape is an ellipse, its axes are aligned with the horizontal and vertical axes of the element.

Both circle and ellipse gradients accept the following keywords as their <size>:

  • closest-side: The ending shape is sized so 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: 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.

If <ending-shape> is specified as circle or is omitted, the <size> may be given explicitly as:

  • <length>: Gives the radius of the circle explicitly. Negative values are invalid.

    Note that percentages are not allowed here; they can only be used to specify the size of an elliptical gradient, not a circular one. This restriction exists because there is are multiple reasonable answers as to which dimension the percentage should be relative to. A future level of CSS may provide the ability to size circles with percentages, perhaps with more explicit controls over which dimension is used.

If <ending-shape> is specified as ellipse or is omitted, <size> may instead be given explicitly as:

  • [<length> | <percentage>]{2}: Gives the size of the ellipse explicitly. The first value represents the horizontal radius, the second the vertical radius. Percentage values are relative to the corresponding dimension of the gradient box. Negative values are invalid.
<color-stop>
A <color> value followed by an optional color stop position. The color stop position can be set in percentage values or fixed length values such as px or em, among others. Color stops are positioned along the gradient ray, and are used to specify the points along that line that colors start at.

A color-stop can be placed at a negative location; though the negative region of the gradient ray is never directly consulted for rendering, color stops placed there can affect the color of non-negative locations on the gradient ray through interpolation or repetition. For example, radial-gradient(red -50px, yellow 100px) produces an elliptical gradient that starts with a reddish-orange color in the center (specifically, #f50) and transitions to yellow. Locations greater than 100% simply specify a location a correspondingly greater distance from the center of the gradient.

Notes

Some combinations of position, size, and shape will produce a circle or ellipse with a radius of 0. This will occur, for example, if the center is on a gradient box edge and closest-side or closest-corner is specified or if the size and shape are given explicitly and either of the radii is zero. In these degenerate cases, the gradient must be rendered as follows:

  • If the ending shape is a circle with zero radius: Render as if the ending shape was a circle whose radius was an arbitrary very small number greater than zero. This will make the gradient continue to look like a circle.
  • If the ending shape has zero width (regardless of the height): Render as if the ending shape was an ellipse whose height was an arbitrary very large number and whose width was an arbitrary very small number greater than zero. This will make the gradient look similar to a horizontal linear gradient that is mirrored across the center of the ellipse. It also means that all color-stop positions specified with a percentage resolve to 0px.
  • Otherwise, if the ending shape has zero height: Render as if the ending shape was an ellipse whose width was an arbitrary very large number and whose height was an arbitrary very small number greater than zero. This will make the gradient look like a solid-color image equal to the color of the last color-stop, or equal to the average color of the gradient if it’s repeating.

Examples

The following is an example creating black-and-white radial stripes using repeating-radial-gradient():

.element {
    /* ... */
    background-image: repeating-radial-gradient(circle at 0% 50%, white 0px, white 20px, black 20px, black 40px);
}
                
rrg-4
repeating-radial-gradient(circle at 0% 50%, white 0px, white 20px, black 20px, black 40px);

Live Demo

Play with the values of the repeating-radial-gradient() function to see how the gradient changes.

View this demo on the Codrops Playground

Browser Support

CSS Repeating Gradients

Method of defining a repeating linear or radial color gradient as a CSS image.

W3C Candidate Recommendation

Supported from the following versions:

Desktop

  • 26
  • 16
  • 10
  • 12
  • 6.1

Mobile / Tablet

  • 7.0
  • 4.4
  • No
  • 61
  • 55

* denotes prefix required.

  • Supported:
  • Yes
  • No
  • Partially
  • Polyfill

Stats from caniuse.com

Written by

Last updated December 11, 2016 at 10:44 pm by Mary Lou

Do you have a suggestion, question or want to contribute? Submit an issue.