Introduction to gradients

Back to the index.

Detailed desktop table
Detailed mobile table

The problem with gradients is that they are a syntactic nightmare. This page gives some more information, as well as workarounds.

I test only two syntaxes: the new, standards-compliant one without prefixes, and the -webkit-prefixed middle syntax. (No other prefixes!)

All desktop browsers meanwhile support the new syntax, but a lot of mobile ones still need the prefixed middle syntax. The bottom line is that you should use both until the WebKit-based browsers support the new syntax. So far only Safari does.

The tests below should work in a browser in order to consider it at all. It uses the combined syntax.

Main test

This is the main gradient test. If a browser fails it, it gets a No and I don’t investigate it any further.

This is an example of a cross-browser linear gradient.

background: -webkit-linear-gradient(0deg,red 10%,yellow 30%,green 60%);
background: linear-gradient(90deg,red 10%,yellow 30%,green 60%);

This is an example of a cross-browser radial gradient.

background: -webkit-radial-gradient(60% bottom,circle closest-corner,red 10%,yellow 30%,green 60%);
background: radial-gradient(circle closest-corner at 60% bottom,red 10%,yellow 30%,green 60%);

The two syntaxes

The combined syntax for linear-gradients is:

-webkit-linear-gradient([<direction> | <angle>],<color-stop>[,<color-stop>]) // MIDDLE
linear-gradient([to <direction> | <angle>],<color-stop>[,<color-stop>]) // NEW

The combined syntax for radial-gradients is:

-webkit-radial-gradient(<position>,<shape> <size>,<color-stop>[,<color-stop>]) // MIDDLE
radial-gradient(<shape> <size> at <position>,<color-stop>[,<color-stop>]) // NEW

Let’s deconstruct these commands.

Command New syntax Middle syntax
Test page
A color stop consists of a color and a stop. The color can be of any syntax. The stop is the point at which the color reaches full saturation. After that the gradient goes on to the next color.
There are no differences between the two syntaxes.
Test page
to left means the linear gradient goes from right to left. right means the linear gradient goes from right to left.
Test page
angle1 = 90 - angle2
This works from new to middle and from middle to new.
0deg means bottom. The angles proceed clockwise. 0deg means left. The angles proceed counterclockwise.
Test page
ellipse (default) or circle. Do not mix with sizes as length.
<size> as keyword
Test page
closest-corner, closest-side, farthest-corner, farthest-side.
These keywords indicate where the last color reaches full saturation.
<size> as length
Test page
Do not mix with explicit shapes.
Horizontal first, then vertical. Any unit allowed. If only one length is given, the gradient becomes a circle. In that case, percentages are not allowed. Horizontal first, then vertical. Any unit allowed. There must be two values.
Test page
Any unit, or keywords such as bottom, preceded by at. Horizontal first, then vertical. Any unit, or keywords such as bottom. Horizontal first, then vertical.
Test page
In order to create a repeating syntax, add repeating- to the property name, and make sure the last color stop is a repeat of the first.

Background: old, middle, and new syntax

The problem with gradients is that the spec writers and browser vendors changed their mind not once but twice. Thus we have three sets of syntax, and all three occasionally crop up even today. I call these old, middle, and new syntax.

Fortunately, you can ignore the old syntax altogether. Trident, Gecko, and Presto support new syntax, so they’re not the problem, either. The problem is WebKit, and especially the time it will take to carry the new syntax to all mobile browsers.

These are the three syntaxes:

  1. Old syntax was supported back in 2010 or so. When using unprefixed middle syntax, you occasionally get old results, depending on the browser.
  2. Middle syntax was implemented when the February 2011 draft was published. All browsers used prefixes to distinguish middle syntax from old, and thus all prefixed gradients use middle syntax.
  3. New syntax was implemented when the current spec was published in April 2012. All browsers implemented it prefixless to distinguish new syntax from middle, and thus most unprefixed gradients use new syntax, unless it’s an old old holdout.

Generally, this is the browser implementation:


Be careful when using online resources for gradient syntax. Always check the date, and ignore articles written before May 2012.

If you encounter the following syntax, the article discusses old syntax and should not be used:

-webkit-gradient(linear,yaddah,yaddah); // IGNORE ENTIRE TUTORIAL!

Here are a few reliable sources: