Learn CSS radial-gradient in 10 minutes or less

With theradial-gradient() function in CSS, you can draw a nice background on any website, without using image-editing software, such as these icons:

Image source: CSS Tricks. The CSS code is available at CodePen.

However, learning how to use radial-gradient is rather hard. The documentation at MDN is confusing rather than helpful, with the following syntax:

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> ]?

The W3Schools is slightly better, but the examples are confusing rather than helpful. For instance, with this example code

background: radial-gradient(red 5%, green 15%, blue 60%);

it’s not immediately clear what role these percentage values play. There is no explanation.

The usually helpful CSS Tricks only scratches the surface, without explaining what these percentage values are.

After a long series of trial and error, I’ve figured it out. I wouldn’t have spent such an amount of time if someone had explained to me in the following way:

Three sets of parameters

First of all, it’s useful to see the radial-gradient() function taking three sets of parameters each of which is separated by comma: shape, start color, and end color.

There can be three colors or more in the parameters. But for the ease of exposition, let’s stick to two-color cases. We will handle three or more colors at the end. Start simple; that’s always the best way to learn something new.

1. Shape

The shape parameter consists of three parts: (1) the pattern of radiation: ellipse or circle, (2) where to end the radiation, (3) where to start the radiation.

The default values are ellipse farthest-corner at center. That is, the radial pattern is anellipse, ending at the farthest-corner of the box, and starting at center of the box. This will look like this:

Image source: CSS Tricks

Since these are the default values, they are not explicitly specified in this example.

1.1 Ellipse or Circle

For a circular pattern, you can replace ellipse with circle. Alternatively, you can directly specify the radius such as 8em. If you use two different values (e.g., 8em 4em) you’re back to an ellipse with the first value referring to the horizontal length.

To sum up, the first part of the shape parameter can be either

• circle
• one length value (e.g. 8em)

for a circular pattern, and

• ellipse (default)
• two length values (e.g. 8em 4em)

for an elliptical pattern.

1.2 Where to stop the radiation

To stop the radiation at the closest side of the box, replace farthest-corner with closest-side:

Image source: CSS Tricks

For other options that replace farthest-corner, see this section of MDN documentation (under the heading of <extent-keyword>).

1.3 Where to start the radiation

To start the radiation pattern from a place other than the center, replace at center with, say, at top right:

Image source: CSS Tricks

For other ways of setting the starting point, see this MDN documentation.

2. Start color

The second set of parameters concerns the starting color. If only color is specified, the gradation (i.e. blending into the end color) immediately starts from the starting point. If the color code is followed by a percentage value, however, the blending does not start until that fraction of the axis:

This diagram explains what location the percentage value indicates. Image source: MDN

So if you specify

radial-gradient(circle closest-side, red 50%, green)

you get a blurred version of the flag of Bangladesh like this:

Drawn by myself with CodePen

Notice that the uniformly red circle spreads up to 50% of the axis from the center to the edge. The blending with the end color of green starts from there.

3. End color

The third set of parameters concerns the end color. If the color code is followed by a percentage value, the blending with the start color stops at that fraction of the axis (rather than it begins as for the start color).

This was the source of my confusion. The meaning of percentage values is different for start and end colors.

So if you specify

radial-gradient(circle closest-side, red 50%, green 60%)

up to the 50% of the axis, it’s uniformly red (as in the previous example); from 50% to 60%, red gradually turns into green, and from the 60% of the axis, it’s uniformly green:

Drawn by myself with CodePen

Adding a middle color

There can be more than two colors in the radial pattern. If you specify

radial-gradient(circle, red, yellow, green)

red starts blending with yellow first; and when it completely turns into yellow, the blending with green starts. So we have an image like this:

Created by myself with CodePen

If you add a percentage value to the middle color, the blending of the start color with the second color stops there while the blending with the end color starts there. For example,

radial-gradient(circle, red, yellow 25%, green)

gives us

Created by myself with CodePen

Notice that we see a ring of the middle color (yellow in this example). And the percentage value after the middle color specifies where this ring is located.

Drawing a ring

Which means we can actually draw a ring with the radial-gradient() function. With the following code

radial-gradient(circle, black 49%, yellow 50%, black 51%)

the blending of the start color of black with yellow won’t start up to 49%. Then it blends into yellow only from 49% to 50%. It’s effectively a sudden change in color from black to yellow. Then from 50% to 51%, yellow turns into black, effectively in a sudden fashion as well. The result is a nice yellow ring against the black background:

Drawn by myself with CodePen

Dealing with Opera Mini

Last but not least, we should consider the browser compatibility of theradial-gradient() function. The caniuse.com shows that it’s compatible with all browsers except one: Opera Mini.

I’ve only recently learned that Opera Mini is a very popular mobile browser in Africa:

Image source: Rad Devon

If your website heavily depends on theradial-gradient() function, many people in Africa cannot properly see it.

So we should add a fallback option. Opera Mini itself recommends the following, whenever you use radial-gradient or its cousin linear-gradient:

button {  
  background: black;
  background: linear-gradient(
    to bottom right,
    red,
    rgba(255, 0, 0, 0)  
  );  
  color: white; 
}

In this example, without specifying black as the background color, the white letters will disappear into the default white background, when browsed with Opera Mini.

So whenever using radial-gradient, just consider those Opera Mini users in less developed countries and add a simplified version of the background so that the webpage content will be legible for them.

I hope this article helps you quickly understand the basics of theradiant-gradient() function.