CSS Radial Gradient

When we talk about gradients, it's worth beginning with the fact that gradients are an image replacement in CSS. That's a fancy way of saying that creating a gradient in CSS provides the browser with instructions for painting an image on the screen rather than you providing the browser with the source URL of a file you created in an image editing application, like Photoshop or Sketch. It's a native CSS way for doing the same thing in code and, as such, gradients are included in the CSS Image Values and Replaced Content specification.

A radial gradient differs from a linear gradient in that it starts at a single point and emanates outward. Gradients are often used to simulate a light source, which we know isn't always straight. That makes them useful to make the transitions between colors seem even more natural.

The default is for the first color to start in the center center position of the element and then fade to the end color toward the edge of the element. The fade happens at an equal rate no matter which direction.

The source of a radial gradient moves from the center outward.

Syntax

The radial-gradient() notation is used on either the background or background-image property in CSS. This makes total sense when we recall that gradients are basically the CSS to create images that we would otherwise make in image editing software and place on a background property anyway.

Official Syntax

Here is how the official spec outlines the syntax for a radial gradient:

<radial-gradient> = radial-gradient(
  [ [ <shape> || <size> ] [ at <position> ]? , |
    at <position>, 
  ]?
  <color-stop> [ , <color-stop> ]+
)

It might be a little helpful to translate that into basic English:

Hey, element! Paint a radial gradient in some shape at some size that is located in these positions. Oh, and make sure it starts with this color and stops at this color.

Values

The radial-gradient notation accepts the following values noted above:

  • shape: Determines the shape of the gradient follows when transitioning outward, from one color to the next. Since we're talking about radial gradients, the shapes are limited to being circular in nature. We can omit this value and the notation will measure the element's side lengths to determine whether one value better matches the situation. For example, an element that is a perfect square would be a great match for circle whereas anything rectangular is ripe for ellipse.
    • circle
    • ellipse
  • size: Influences the ending shape of the gradient by taking the shape value and instructing where the gradient should end based on the center of the shape. This can be expressed by name or an exact measure of length.
    • closest-side: The gradient will end at side closest to the center of the shape. If two sides match this criteria, then it will be evenly distributed.
    • farthest-side (default): The opposite of closest-side, where the gradient will end at the side furthest from the shape's center.
    • closest-corner: The gradient will end at the corner that matches as the closest to the shape's center.
    • farthest-cornerThe opposite of closest-corner, where the gradient ends at the corner that is located furthest from the shape's center.
    • <length>: We can specify a numeric value that serves as the circle's radius. This has to be stated in positive pixels or relative units. Sorry, no negative units or percentages allowed because a negative circle would be vacuum and percentages can be relative to any number of surrounding values.
    • <length or percentage: A second numeric value can be provided to declare the explicit size of an ellipse, but not a circle. Again, negative values are a no-no, but percentages are fair game since the size is relative to the gradient box rather than the element.
  • position: This works very much the same way that it does on background-position. That means top, right, left, and center all work here, as well as combinations where two named values (e.g. top center) are provided. We can also specify an exact position using a numeric value, including percentage, all of which are relative to the element's bounding box. Default is center center.
  • color-stop: These are color values that define the gradient. Any color value is accepted here, including hex, named, RGB and HSL.

Usage

Here's how that looks at perhaps its most basic. Note that we are not declaring the shape>, size, position or color-stop values, which all default to values placing the gradient at the very center of the element and transition evenly between the declared color values.

.gradient {
  background-image:
    radial-gradient(
      yellow,
      #f06d06
    );
}

See the Pen blcqw by Chris Coyier (@chriscoyier) on CodePen.

You can see how that gradient assumes the shape is ellipse. That's because the element itself is not a perfect square. In that case, it would have assumed a circle instead. Pretty smart! Here's what would happen if we had explicitly declared circle as the shape value:

.gradient {
  background-image:
    radial-gradient(
      circle,
      yellow,
      #f06d06
    );
}

Notice the gradient is circular, but only fades all the way to the ending color along the farthest edge. Now we can explicitly declare the position value to ensure that the fade ends by the "closest-side" of the shape instead, like this:

.gradient {
  background-image:
    radial-gradient(
      circle closest-side,
      yellow,
      #f06d06
    );
}

See the Pen EFyvp by Chris Coyier (@chriscoyier) on CodePen.

The possible values there are: closest-corner, closest-side, farthest-corner, farthest-side. You can think of it like: "I want this radial gradient to fade from the center point to the __________, and everywhere else fills in to accommodate that."

A radial gradient doesn't have to start at the default center either, you can specify a certain point by using "at ______" as part of the first parameter, like:

.gradient {
  background-image:
    radial-gradient(
      circle at top right,
      yellow,
      #f06d06
    );
}

I'll make it more obvious here by making the example a square and adjusting a color-stop:

See the Pen iuaDL by Chris Coyier (@chriscoyier) on CodePen.

Browser Support

Browser support for radial-gradient() is largely the same as linear-gradient(). The exception is a very old version of Opera. Right when they started supporting gradients they only accounted for linear and not radial.

But similar to linear-gradient(), if your browser support needs to go super deep, then you might consider using Autoprefixer or a similar tool that handles vendor prefixing for you rather than having to manage those yourself.

This browser support data is from Caniuse, which has more detail. A number indicates that browser supports the feature at that version and up.

Desktop

ChromeOperaFirefoxIEEdgeSafari
10*11.6*3.6*10125.1*

Mobile / Tablet

iOS SafariOpera MobileOpera MiniAndroidAndroid ChromeAndroid Firefox
5.0-5.1*12*No4*6156

Additional Resources

  • CSS Image Values and Replaced Content Module Level 4: The official specification for the notation. CSS Gradients were introduced in Level 3 and radial gradients have been left unchanged as of today in the Level 4 working draft.
  • MDN Docs: Mozilla Developer Network's explanation of the feature and specification, with examples.
  • Mastering CSS3 Gradients: Slides from Lea Verou's talk back in 2011 that is still an awesome resource.

Submit a Comment

Posting Code

You may write comments in Markdown. This makes code easy to post, as you can write inline code like `<div>this</div>` or multiline blocks of code in triple backtick fences (```) with double new lines before and after.

Code of Conduct

Absolutely anyone is welcome to submit a comment here. But not all comments will be posted. Think of it like writing a letter to the editor. All submitted comments will be read, but not all published. Published comments will be on-topic, helpful, and further the discussion or debate.

Want to tell us something privately?

Feel free to use our contact form. That's a great place to let us know about typos or anything off-topic.

icon-anchoricon-closeicon-emailicon-linkicon-logo-staricon-menuicon-nav-guideicon-searchicon-staricon-tag