A Complete Guide to CSS Gradients

Avatar of Geoff Graham
Geoff Graham on (Updated on )

Like how you can use the background-color property in CSS to declare a solid color background, you can use the background-image property not only to declare image files as backgrounds but gradients as well. Using CSS gradients is better for control and performance than using an actual image (of a gradient) file.

Brought to you by DigitalOcean

DigitalOcean has the cloud computing services you need to support your growth at any stage. Get started with a free $200 credit!

CSS gradients are typically one color that fades into another, but CSS allows you to control every aspect of how that happens, from the direction and the shape to the colors and how they transition from one to another. In fact, there are three types of gradients: linear, radial, and conic. Here’s the basic syntax for each one:

/* Basic linear CSS gradient examples */
background-image: linear-gradient(#ff8a00, #e52e71);
background-image: linear-gradient(to right, violet, darkred, purple);
background-image: linear-gradient(40deg, rgb(255 0 0) 60%, orange);

/* Basic radial CSS gradient examples */
background-image: radial-gradient(#ff8a00, #e52e71);
background-image: radial-gradient(circle at top right, #ff8a00, red, #e52e71);

/* Basic conic CSS gradient examples */
background-image: conic-gradient(#ff8a00, #e52e71);
background-image: conic-gradient(red 50deg, yellow 100deg, lime 200deg, aqua, blue, magenta, red);

Linear CSS gradients

Perhaps the most common type of CSS gradient we see in web design is the linear-gradient(). It’s called “linear” because the colors flow from left-to-right, top-to-bottom, or at any angle you chose in a single direction.

Syntax

The syntax is is declared on either the background (shorthand) or background-image property in CSS. It reads like this in plain English:

Create a background image that is a linear gradient that moves [in this direction or at this angle] and starts with [one color] and ends with [another color].

The official syntax looks more like this:

linear-gradient(
  [ <angle> | to <side-or-corner> ]? ,
  <color-stop-list>
)
<side-or-corner> = [to left | to right] || [to top | to bottom]
Usage

Let’s start with the most basic example, a two-color CSS gradient that goes from top to bottom:

.gradient {
  background-image: linear-gradient(#ff8a00, #e52e71);
}

Nice, right? Notice that we did not declare the angle in the example above. CSS will assume to bottom in that scenario, where #ff8a00 is the starting color that transitions into the next color, #e52e71.

We could have written the same thing two other ways:

/* Explicitly declare the direction */
background-image: linear-gradient(to bottom, #ff8a00, #e52e71);

/* Explicitly declare the angle, in degrees */
background-image: linear-gradient(180deg, #ff8a00, #e52e71);
Changing direction

To make the CSS gradient go from left-to-right, we pass an additional parameter at the beginning of the linear-gradient() function, starting with the word to which indicates the direction. Let’s break the property value into separate lines so it’s easier to see what’s going on.

.gradient {
  background-image:
    linear-gradient(
      to right,
      #ff8a00, #e52e71
    );
}

Neat, now the colors transition from the left edge to the right edge of the element!

This to syntax works for corners as well. For instance if you wanted the axis of the gradient to start at the bottom left corner and go to the top right corner, you could say to top right:

.gradient {
  background-image:
    linear-gradient(
      to top right,
      #ff8a00, #e52e71
    );
}

If that box was a perfect square, the gradient’s angle would have been 45deg, but since it’s not, it isn’t. If you wanted to make sure it was 45deg, you could declare the exact angle, only dropping to from the syntax:

.gradient {
  background-image:
    linear-gradient(
      45deg, 
      #ff8a00, #e52e71
    );
}
Multiple colors

We aren’t limited to just two colors! In fact, we can have as many comma-separated colors as we want. Here’s four:

.gradient {
  background-image:
    linear-gradient(
      to right, 
      red, 
      #f06d06, 
      rgb(255, 255, 0), 
      green
    );
}
Browser support

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

ChromeFirefoxIEEdgeSafari
10*36101215.4

Mobile / Tablet

Android ChromeAndroid FirefoxAndroidiOS Safari
1261274*15.4

Radial CSS gradients

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

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.

The official syntax goes like this:

radial-gradient(
  [ <ending-shape> || <size> ]? [ at <position> ]? ,
  <color-stop-list>
);

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:

  • 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-corner: The opposite of closest-corner, where the gradient ends at the corner that is located furthest from the shape’s center.
    • radius: 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.
      • 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 toprightleft, 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 shapesizeposition 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(
      #ff8a00,
      #e52e71
    );
}

Looking for more radial gradient examples? Patrick Brosset has many of them in his deep-dive on radial gradients.

Changing shape

See how that gradient assumes the shape is ellipse in the examples above? 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,
      #ff8a00,
      #e52e71
    );
}
Changing position

Notice the gradient in the demos have been circular and fade all the way to the ending color along the farthest edge. 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,
      #ff8a00,
      #e52e71
    );
}

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

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

.gradient {
  background-image:
    radial-gradient(
      circle at top right,
      #ff8a00,
      #e52e71
    );
}
Browser support

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

ChromeFirefoxIEEdgeSafari
10*36101215.4

Mobile / Tablet

Android ChromeAndroid FirefoxAndroidiOS Safari
1261274*15.4
Related articles

Conic CSS gradients

A conic gradient is similar to a radial gradient. Both are circular and use the center of the element as the source point for color stops. However, where the color stops of a radial gradient emerge from the center of the circle, a conic gradient places them around the circle.

They’re called “conic” because they tend to look like the shape of a cone that is being viewed from above. Well, at least when there is a distinct angle provided and the contrast between the color values is great enough to tell a difference.

Syntax

The conic gradient syntax is easier to understand in plain English:

Make a conic-gradient that is located at [some point] that starts with [one color] at some angle and ends with [another color] at [some angle]

This is the official syntax:

conic-gradient(
  [ from <angle> ]? [ at <position> ]?,
  <angular-color-stop-list>
)
Usage

At its most basic level, it looks like this:

.gradient {
  background-image:
    conic-gradient(
      #ff8a00, #e52e71
    );
}

…where it is assumed that the location of the gradient starts at the very center of the element (50% 50%) and is evenly distributed between the twi color values.

We could have written this in several other ways, all of which are valid:

.gradient {
  /* Original example */
  background-image: conic-gradient(#ff8a00, #e52e71);
  /* Explicitly state the location center point */
  background-image: conic-gradient(at 50% 50%, #ff8a00, #e52e71);
  /* Explicitly state the angle of the start color */
  background-image: conic-gradient(from 0deg, #ff8a00, #e52e71);
  /* Explicitly state the angle of the start color and center point location */
  background-image: conic-gradient(from 0deg at center, #ff8a00, #e52e71);
  /* Explicitly state the angles of both colors as percentages instead of degrees */
  background-image: conic-gradient(#ff8a00 0%, #ff8a00, #e52e71);
  /* Explicitly state the angle of the starting color in degrees and the ending color by a full turn of the circle */
  background-image: conic-gradient(#ff8a00 0deg, #e52e71 1turn);
}

If we do not specify an angle for the colors, then it is assumed that the gradient is evenly divided between the colors, starting at 0deg and ending at 360deg. That creates a “hard stop” where the colors bump right up to one another at 0deg and 360deg. If we introduce a third value, then that creates a smoother gradient and we start to get that cool cone-looking perspective.

.gradient {
  background-image:
    conic-gradient(
      #ff8a00,
      #e52e71,
      #ff8a00
    );
}

We can have fun with conic gradients. For example, we can use it to create the same sort of pattern you might see in a color picker or the infamous Mac spinning beach ball indicator:

.conic-gradient {
  background-image:
    conic-gradient(
      red,
      yellow,
      lime,
      aqua,
      blue,
      magenta,
      red
    );
}

Or, let’s try a simple pie chart by adding hard stops between three color values:

.gradient {
  background-image:
    conic-gradient(
      lime 40%,
      yellow 0 70%,
      red 0
    );
}
Browser support

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

ChromeFirefoxIEEdgeSafari
6983No7912.1

Mobile / Tablet

Android ChromeAndroid FirefoxAndroidiOS Safari
12612712612.2-12.5

Repeating CSS gradients

Repeating gradients take a trick we can already do with the creative use of color-stops on the linear-gradient() and radial-gradient() notations, and bakes it in for us. The idea is that we can create patterns out of the gradients we create and allow them to repeat infinitely.

Syntax

There are three types of repeating gradients, all three of which are currently supported in the official specification and one that is in the current working draft. The syntax for each notation is the same as its related gradient type. For example, repeating-linear-gradient() follows the same syntax as linear-gradient().

Repeating gradientRelated notationExample
repeating-linear-gradientlinear-graadientrepeating-linear-gradient(45deg, #ff8a00, #ff8a00 10px, #e52e71 10px, #e52e71 20px);
repeating-radial-gradientradial-gradientrepeating-radial-gradient(#ff8a00 0 8%, #e52e71 8% 16%);
repeating-conic-gradientconic-gradientrepeating-conic-gradient(from 0deg, #ff8a00 0deg 30deg, #e52e71 30deg 60deg);

Usage

Here’s a repeating linear gradient that alternates between two colors every 10 pixels at a 45-degree angle:

.gradient {
  background-image:
    repeating-linear-gradient(
      45deg,
      #ff8a00,
      #ff8a00 10px,
      #e52e71 10px,
      #e52e71 20px
    );
}

We can do the same sort of thing, but with a radial gradient. The difference? Besides the notation itself, we’re defining the shape and starting point:

.gradient {
  background-image:
    repeating-radial-gradient(
      circle at 0 0,
      #ff8a00,
      #ff8a00 10px,
      #e52e71 10px,
      #e52e71 20px
    );
}

Conic gradients aren’t much different! Again, the big difference between radial and conic gradients is that conic colors transition around the element, where colors in radial gradients transition from the center of the gradient source.

.gradient {
  background-image:
    repeating-conic-gradient(
      from 0deg, 
      #ff8a00 0deg 30deg, 
      #e52e71 30deg 60deg
  );
}
Browser support

This is specifically for linear and radial repeating gradients.

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

ChromeFirefoxIEEdgeSafari
10*3.6*10125.1*

Mobile / Tablet

Android ChromeAndroid FirefoxAndroidiOS Safari
1261274*5.0-5.1*

Tricks!

Patterns

We saw how gradients can create interesting patterns when we looked at repeating gradients. But there are many other patterns we can create! Like checkerboards:

We can also make a repeating chevron pattern:

Chris has a snippet that makes a graph paper pattern:

These patterns are well documented on the web, but check out Lea Verou’s CSS gradient pattern gallery for some truly mind-bending examples.

Border gradients

We can create borders out of gradients!

We can even use the pattern trick for a fun border effect:

Or, hey, we can put hard stops to use for an overlapping content effect:

Animated gradients

We can use background-position tp make it appear as though the transition between colors in a gradient is moving.

But, as is the case with any animation, be mindful of accessibility, particularly those who are sensitive to motion. Check out the Accessibility section for more.

Check out this demo by Marty! This is a super clever use of radial gradients to simulate sunlight based on the position of the mouse cursor.

Accessibility

CSS gradients should consider the contrast between background and foreground colors, just as you would working with background-color. The trick is to make sure that all the colors used in the gradient and the transitions between them don’t affect the legibility of any content that sits on top of it. That’s where using a contrast checker comes in handy.

Something else to watch for? Animations. Transitioning between two solid background colors, say on hover, isn’t usually an issue. But if background-position is used to make it appear that a gradient is moving, then it’s worth considering the prefers-reduced-motion media query so the animation is served to the right users.

Specification