A Complete Guide to CSS Gradients

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]

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);

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
    );
}

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
    );
}

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.

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 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.

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(
      #ff8a00,
      #e52e71
    );
}

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

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
    );
}

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-corner, closest-side, farthest-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
    );
}

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>
)

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
    );
}

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().

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
  );
}

This is specifically for linear and radial repeating gradients.

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.

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:

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.