Copyright © 2009 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
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.
This is a public copy of the editors' draft. It is provided for discussion only and may change at any moment. Its publication here does not imply endorsement of its contents by W3C. Don't cite this document other than as 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.
url()’ notation
image()’ notation
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.
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:
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.
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].
url()’ notationThe 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.
image()’ notationThe ‘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 [[CSS3BACKGROUND]], 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.
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:
This specification defines the following units as part of the <resolution> value type:
px’ unit
The default resolution of raster images in CSS is
‘1dppx’.