CSS3 Gradients

Introduction

WebKit paved the way for gradients in CSS by adding support for -webkit-gradient back in early 2008, and they’ve become widely used since their introduction.

Over the past several months, the CSS Working Group has had extended discussions about making the gradient syntax easier to use, and recently Tab Atkins included a proposal in the latest draft of the Image Values and Replaced Content module. WebKit and Mozilla have now implemented this proposal so that web authors can experiment with it, and provide feedback to the Working Group. Note that the proposal is still an editor’s draft, which means that it’s still possible, and even likely to change due to user feedback.

The main goal of the new syntax is simplicity; it’s now really easy to code up common gradients, as you’ll see in the examples below. A secondary goal was to specify something where implementations were compatible across browsers.

If you’re not already running one, go and grab a recent nightly build so that you can see the examples in this post.

Here are some simple examples (note that all these examples are resizable, so you can see how resizing the box affects the gradients):

Don’t forget that gradients are a type of generated image, not a property. This means that you can use them anywhere you’d use a url(image.png).

The New Gradient Syntax

The new syntax has four gradient functions:

• linear-gradient()
• radial-gradient()
• repeating-linear-gradient()
• repeating-radial-gradient()

The names are pretty self-explanatory, but I’ll say more about repeating gradients later. One nice thing is that the syntax for the repeating and non-repeating variants is identical.

Because this specification is still in draft form, we’ve prefixed these gradient functions with -webkit- prefix. Later when the specification is out of the draft phase you’ll be able to use them without the prefix.

Linear Gradients

Since filling the element’s box is the most common use for gradients, this is the standard behavior for linear gradients. All that you have to think about is what direction you want the gradient to run in.

There are two ways to specify this. First, you can specify the side or corner where you want the gradient to start:

You can even omit the first argument, and it will default to top, giving a vertical gradient.

In the second form, you can specify the angle of the gradient axis:

Angles run counter-clockwise, and 0deg is to the right. Note how in all these cases, the gradient is just big enough to fill the box.

Radial Gradients

Radial gradients are a little more complex, because there are more options about how to fill the box. In its simplest form, the gradient is centered in the box, and is large enough to fill it to the corners:

This is equivalent to -webkit-radial-gradient(center, ellipse cover, white, black). That optional first argument, center, can also be a point (just like background-position), which allows you to put the origin somewhere else:

The argument after the position specifies the shape and size of the gradient, in one of two ways. The first uses some keyword for the shape (circle, ellipse) and size (closest-side, closest-corner, farthest-side, farthest-corner, contain, cover) which are self-describing. For example:

If you want to, you can specify the ending radius of the gradient explicitly, and separately for the horizontal and vertical axes:

Color Stops

It’s very easy to specify color stops with the new gradients; in the simplest case, you can just supply a list of colors:

This results in the colors being spread out evenly over the gradient. If you like, you can position specific stops, and let the browser distribute the rest between those:

Those lengths are along the gradient axis, which may be diagonal; percentages are relative to that diagonal length.

Color stops at the same position result in sharp color changes:

Repeating Gradients

The repeating forms, repeating-linear-gradient(), and repeating-radial-gradient(), have exactly the same syntax as the simple forms, but fill in the entire gradient by repeating the stops:

The stops are repeated by just aligning them end-to-end, which often results in a sharp boundary. You can avoid this by repeating the last color:

Changes from -webkit-gradient

You should be able to recreate most of the gradients you made with -webkit-gradient with this new syntax, but there are some changes to be aware of.

First, -webkit-gradient uses a two-point syntax that lets you explicitly state where a linear gradient starts and ends. linear-gradient does away with this in favor of convenient box-filling behavior. If you really want the gradient to stop before the edges of the box, you can do so via color stop placement.

Similarly, radial-gradient no longer allows you to specify different start and end points for radial gradients, so the new radial gradients are always concentric. You can, however, produce elliptical gradients with the new syntax, which was not possible with -webkit-gradient.

So is -webkit-gradient going away? Certainly not! We’ll maintain support for -webkit-gradient for the foreseeable future for all the existing content out there that uses it.

Please Give Feedback

To reiterate, we’ve implemented support for these new gradients so that you, as web developers and authors, can give feedback. The correct forum for discussion of the gradient syntax and behavior is the www-style mailing list. If you find a bug in the implementation, please file a bug at bugs.webkit.org.