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 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.
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 [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.
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’.