CSS3 Box Shadow Syntax Breakdown

This post is just a simple breakdown of CSS3’s box-shadow property, which you can also review on my click chart.

This is mainly written for CSS3 beginners, but does contain some extra info that might be useful to developers already familiar with what’s new in CSS3, including the use of shadows.

The Full Syntax

Here is what a box-shadow declaration looks like, with all the possible values and vendor prefixes included:

.box {
  -webkit-box-shadow: #c4c4c4 3px 3px 10px 5px inset;
  -moz-box-shadow: #c4c4c4 3px 3px 10px 5px inset;
  box-shadow: #c4c4c4 3px 3px 10px 5px inset;
}

You can view the above code in action here.

So what do these values represent?

Value 1: Color

The first value is the color of the shadow. This is any valid color value. The color of the shadow is not naturally semi-transparent, which is a common trait of graphic shadows. But instead, the author has to define a color, along with an optional transparency value, to make the shadow have transparency. For example, you can use HSLA or RGBA color values, both of which allow an alpha channel setting. Or you can just use a fully opaque light grey, like I’m using.

According to the spec, the color value can be omitted and you can define the color of the shadow using the color property. But for some reason, this doesn’t work in WebKit. Other browsers handle this fine, which you can test using this demo.

The color value can be placed after the length values, or before them, but not in between any lengths pairs. So you can’t do this:

.box {
  box-shadow: 3px 3px #c4c4c4 10px 5px;
}

The browser will ignore that whole line. So the color value needs to be at the beginning or at the end (assuming you don’t have an inner shadow, discussed below).

Value 2: Horizontal Offset

The next value can be positive or negative, and can be any valid CSS length value. This value specifies the horizontal offset. A positive value pushes the shadow to the right, while a negative value pushes it to the left. This offset is relative to the position of the box on which the shadow is applied.

To show the effect, here is the same shadow from above, but with a 100px horizontal offset.

Value 3: Vertical Offset

The third value is a vertical offset, and has the exact same specs as the horizontal offset, except the shadow will be offset either up or down (i.e. vertically), depending on whether the value is positive or negative.

Again, here is the same shadow, with an added 100px vertical offset.

Value 4: Blur Radius (optional)

The fourth value again uses any valid length value, except this time a negative value has no effect so will be interpreted as “0”. The blur radius defines the sharpness or blurriness of the shadow. The lower the value, the sharper the shadow. A high value will create a large amount of blur.

Here’s an example that has a very high blur radius. And this example shows what happens when the value is negative.

The third length value will always be interpreted as a blur value.

Value 5: Spread Distance (optional)

The next value, another length value, can be either positive or negative, and will define how much the shadow will expand beyond any already-defined offset values. A negative value will make the shadow get smaller, or contract.

This example shows how a large spread distance can appear to negate any offset values. And this example shows the effect of a large spread distance with an inner shadow (more on this below).

Although the blur value is optional, you can’t exclude the blur value if you include the spread, otherwise the spread value will simply be read as a blur value. To fix this, you simply use a value of “0” for the blur, then include your spread value. So a spread value will never be read unless there are three other length values included.

Value 6: Inset (optional)

This value works similar to an HTML Boolean attribute. In other words, its existence means “use an inner shadow” and its exclusion is interpreted as an outer shadow. So you don’t have to use “outset”, you simply omit it when you don’t want an inset shadow.

The inset value must appear either first or last in the declaration, otherwise the whole line will be negated.

Multiple Shadows

You can apply more than one shadow to a single element simply by comma separating the shadows, within a single box-shadow declaration, like this:

.box {
  box-shadow: #c4c4c4 10px 10px 10px 5px, #c4c4c4 30px 20px 10px 10px;
}

Here are some weird staggered multiple shadows.

The shadows are applied from front to back, so the first shadow will overlap the second, the second will overlap the third, and so on. This is the opposite of how HTML elements are stacked with z-index.

Some Final Notes on Box Shadows

Here are some things to note about the implementation of shadows:

• Browser support is very good, with the only big problems being IE6-8
• You can polyfill using CSS3 PIE, this script, or cssSandpaper, but you’re probably better off just degrading to no shadow
• Browsers that require vendor prefixes: Safari 3.1 up to 5.0; Firefox 3.5 and 3.6; Chrome up to version 9; some mobile browsers
• A large shadow will not push other elements away, nor will it cause scrollbars if it overflows a parent
• A box shadow will be rounded to reflect any border radius setting, but it will not be affected by a border image
• As pointed out here, box shadows have the potential to cause performance problems, so use them sparingly