CSS Image Values Module Level 3

W3C Working Draft 23 July 2009

This version:
Latest version:
Previous version:
Elika J. Etemad


This CSS Image Values module defines the syntax for <image> values in CSS. <image> values can be a single URI to an image, a list of URIs denoting a series of fallbacks, sprites (image slices), or gradients.

Status of this document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

The (archived) public mailing list www-style@w3.org (see instructions) is preferred for discussion of this specification. When sending e-mail, please put the text “css3-images” in the subject, preferably like this: “[css3-images] …summary of comment…

This document was produced by the CSS Working Group (part of the Style Activity).

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This is the first public working draft in the “css3-images” series.

Table of contents

1 Introduction

This section is non-normative.

In CSS Levels 1 and 2, image values, such as those used in the ‘background-image’ property, could only be given by a single URI value. This module introduces additional notations that allow a 2D image to be given as a list of URIs denoting fallbacks, as a slice of a larger image (sprite), and as a gradient.

2 Conformance

A document or implementation cannot conform to CSS Image Values Level 3 alone, but can claim conformance to CSS Image Values Level 3 if it satisfies the conformance requirements in this specification when implementing CSS or another host language that normatively references this specification.

Conformance to CSS Namespaces is defined for two classes:

style sheet
A CSS style sheet (or a complete unit of another host language that normatively references CSS Namespaces).
Someone or something that interprets the semantics of a style sheet. (CSS user agents fall under this category.)

The conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification. All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words "for example" or are set apart from the normative text with class="example", like this:

This is an example of an informative example.

Informative notes begin with the word "Note" and are set apart from the normative text with class="note", like this:

Note, this is an informative note.

3 The <image> value type

The <image> value type denotes a 2D image. It is defined as

<image> = <url> | <sprite> | <image-list>

Image values can be used in many CSS properties, including the ‘background-image’, ‘list-style-image’, ‘cursor’ properties [CSS21].

4 Image References and Image Slices: the ‘url()’ notation

The simplest way to indicate an image is to reference an image file by URI. This is done with the url()’ notation, defined in [CSS21].

In the example below, a background image is specified with ‘url()’ syntax:

background-image: url(wavy.png);

A portion of an image may be referenced (clipped out and used as a standalone image) by use of fragment identifiers. Need a spec to reference here. Expecting to get one from Media Fragments WG.

For example,

background-image: url('logos.png#xywh=10,30,60,20')

uses the 60 pixel by 20 pixel rectangle of logos.png beginning at the point 10 pixels in from the left, 30 pixels down from the top.

Note that quotation marks are required here, because unquoted commas are not allowed in ‘url()’ syntax.

5 Image Fallbacks: the ‘image()’ notation

The ‘image()’ notation allows an author to specify multiple images, each one a fallback for the previous. The UA must use only the first image that it can load and display. The syntax for ‘image()’ is defined as

<image-list> = image( [ <image-decl> , ]* [ <image-decl> ] [ or <color> ]? )

where <image-decl> is given by

<image-decl> = [ <string> | <url-token> ] [ snap? && <resolution> ]?

<url-token> is given as [!#$%&*-~]|{nonascii}|{escape} (i.e. the contents of ‘url()’) using the productions in the CSS2.1 tokenization. The <url-token> must not contain unescaped brackets, commas, white space characters, single quotes (') or double quotes ("); if it does the ‘image()’ containing it is invalid.

Each string or url-token represents the URI of an image. If a resolution is given, then the image must be rendered at the specified resolution. If the ‘snap’ keyword is also specified, and the image is a raster image, then the image must be rendered at the resolution closest to the specified resolution that would result in no pixel rounding. I don't think "no pixel rounding" is the right terminology here... basically we want to avoid blurry images.

The optional color at the end of the list is the fallback color. It is used if, and only if, none of the images can be loaded and displayed (e.g. because they are in unsupported formats, or cannot be found, or are corrupted in some way, or because image loading is disabled in the UA). It is treated as a single-color image with no intrinsic dimensions.

For example, the rule below would tell the UA to load ‘wavy.svg’ if it can; failing that to load ‘wavy.png’ and display it at 150dpi; failing that to display ‘wavy.gif’; and finally, if none of the images can be loaded and displayed, to use the color ‘blue’ to create a dimensionless background image.

background-image: image(wavy.svg, 'wavy.png' 150dpi, "wavy.gif"  or blue);

The ‘background-image’ property specifies that dimensionless images must stretch to cover the entire background positioning area [CSS3BG], so if none of the specified images can be displayed the background will be painted blue. As with any image, this fallback will be painted over the ‘background-color’ (if any).

If the URL for the image ends in a file extension (a period followed by letters) of four ascii letters ([a-zA-Z]) or less, then the UA may skip trying to load images whose file extension matches an image format it knows it does not support. For example, a UA that knows it supports JPEG and GIF, but expects to encounter many PNG and SVG images may choose to skip over images with filenames ending in ‘.png’ or ‘.svg’ without loading them to check their MIME type. However it must not skip over images with filenames ending in extensions it doesn't recognize.

6 Image Sprites

The image sprites syntax is different from image slices noted above. Image slice syntax allows you to specify the coordinates of a region in the image and use that as a standalone image, but all the coordinates must be specified inline. This is great for one-off cutouts, but becomes unnecessarily verbose when the slices fit into a grid structure. The goal of this section is to define a syntax that:

As yet unwritten. Discussions/proposals include:

7 Resolution Units

This specification defines the following units as part of the <resolution> value type:

dots per inch
dots per centimeter
dots per ‘px’ unit

The default resolution of raster images in CSS is ‘1dppx’.



Normative references

Bert Bos; et al. Cascading Style Sheets Level 2 Revision 1 (CSS 2.1) Specification. 23 April 2009. W3C Candidate Recommendation. (Work in progress.) URL: http://www.w3.org/TR/2009/CR-CSS2-20090423/
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. Internet RFC 2119. URL: http://www.ietf.org/rfc/rfc2119.txt

Informative references

Elika J. Etemad; Bert Bos. CSS Backgrounds and Borders Module Level 3. 10 September 2008. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2008/WD-css3-background-20080910