W3C

CSS3 module: Backgrounds

W3C Working Draft 2 August 2002

This version:
http://www.w3.org/TR/2002/WD-css3-background-20020802
Latest version:
http://www.w3.org/TR/css3-background
Previous version:
http://www.w3.org/TR/2002/WD-css3-background-20020219
Editors:
Tim Boland (NIST)
Bert Bos (W3C)

Abstract

CSS (Cascading Style Sheets) is a language for describing the rendering of structured documents (such as HTML and XML) on screen, on paper, in speech, etc. This draft describes the functionality that is proposed for CSS level 3 to describe backgrounds, such as background colors and background images. It includes and extends the functionality of CSS level 2 [CSS2], which builds on CSS Level 1 [CSS1].

Status of this document

This document is a draft of one of the "modules" [CSS3INTRO] for the upcoming CSS3 specification. It not only describes the background functionality that already exists in CSS1 and CSS2, but also proposes new functionality for CSS3 as well as for other languages that may need it.

This document is a working draft of the CSS working group which is part of the style activity (see summary).

The working group believes this draft is stable and it therefore issues a last call for comments, before requesting the status of Candidate Recommendation for the draft. The deadline for comments is 30 August 2002.

Comments on, and discussions of this draft can be sent on the (archived) public mailing list www-style@w3.org (see instructions). W3C Members can also send comments directly to the CSS working group.

This is a working draft and may therefore be updated, replaced or rendered obsolete by other W3C documents at any time. It is inappropriate to use W3C Working Drafts as reference material or to cite them as other than "work in progress". Its publication does not imply endorsement by the W3C membership or the CSS Working Group (members only).

Patent disclosures relevant to CSS may be found on the Working Group's public patent disclosure page.

To find the latest version of this working draft, please follow the "Latest version" link above, or visit the list of W3C Technical Reports.

This document may be available in translations in the future. The English version of this specification is the only normative version.

Table of contents

1. Dependencies with other CSS 3 Modules

2. Context

Members of the CSS Working Group proposed during the Clamart meeting to modularize the CSS specification.

This modularization, and the externalization of the general syntax, of CSS will reduce the size of the specification and allow new types of specifications to use selectors and/or CSS general syntax.

This specification will contain its own test cases, one test per concept introduced in this document. These tests will not be conformance full tests but will be intended to provide users with a way to check if a part of this specification is implemented at least a minima or not or, on the contrary, not implemented at all.

2.1. Changes from CSS 2

'Background-clip', 'background-size', 'background-quantity', 'background-spacing' and 'background-origin' are new.

3. Background

Authors may specify the background of an element (i.e., its rendering surface) as either a color or an image. In terms of the box model [CSS3BOX], "background" refers to the background of the content, padding and border areas. Margins are always transparent so the background of the parent box always shines through.

Background properties are not inherited, but the parent box's background will shine through by default because of the initial 'transparent' value on 'background-color'.

The background of the box generated by the root element covers the entire canvas.

For HTML documents, however, we recommend that authors specify the background for the BODY element rather than the HTML element. User agents should observe the following precedence rules to fill in the background: if the value of the 'background' property for the HTML element is different from 'transparent' then use it, else use the value of the 'background' property for the BODY element. If the resulting value is 'transparent', the rendering is undefined.

According to these rules, the canvas underlying the following HTML document will have a "marble" background:

<!DOCTYPE html PUBLIC '-//W3C//DTD XHTML 1.1//EN'
  'http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd'>
<html>
  <head>
    <title>Setting the canvas background</title>
    <style type="text/css">
       body { background: url("http://style.com/marble.png") }
    </style>
  </head>
  <body>
    <p>My background is marble.</p>
  </body>
</html>

3.1. The 'background-color' property

Name: background-color
Value: <color> | inherit
Initial: transparent
Applies to: all elements
Inherited: no
Percentages: N/A
Media: visual

This property sets the background color of an element to a <color>.

Example(s):

h1 { background-color: #F00 }

Note that the keyword 'transparent' was mentioned explicitly as a valid value in CSS2. It is still valid, but it is now implied by the <color> type.

3.2. The 'background-image property

Name: background-image
Value: <uri> | none | inherit
Initial: none
Applies to: all elements
Inherited: no
Percentages: N/A
Media: visual

This property sets the background image of an element. When setting a background image, authors should also specify a background color that will be used when the image is unavailable. When the image is available, it is rendered on top of the background color. (Thus, the color is visible in the transparent parts of the image).

Values for this property are either <uri>, to specify the image, or 'none', when no image is used.

Example(s):

body { background-image: url("marble.gif") }
p { background-image: none }

3.3. The 'background-repeat' property

Name: background-repeat
Value: repeat | repeat-x | repeat-y | no-repeat | inherit
Initial: repeat
Applies to: all elements
Inherited: no
Percentages: N/A
Media: visual

If a background image is specified, this property specifies whether the image is repeated (tiled), and how. All tiling covers the content, padding and border areas of a box. Values have the following meanings:

repeat
The image is repeated both horizontally and vertically.
repeat-x
The image is repeated horizontally only.
repeat-y
The image is repeated vertically only.
no-repeat
The image is not repeated: only one copy of the image is drawn.

Example(s):

body { 
  background: white url("pendant.gif");
  background-repeat: repeat-y;
  background-position: center;
}

A centered background image, with copies repeated up and down
the border, padding and content areas.

One copy of the background image is centered, and other copies are put above and below it to make a vertical band behind the element.

3.4. The 'background-attachment' property

Name: background-attachment
Value: scroll | fixed | inherit
Initial: scroll
Applies to: all elements
Inherited: no
Percentages: N/A
Media: visual

If a background image is specified, this property specifies whether it is fixed with regard to the viewport ('fixed') or scrolls along with the document ('scroll').

Even if the image is fixed, it is still only visible when it is in the background, padding or border area of the element. Thus, unless the image is tiled ('background-repeat: repeat'), it may be invisible.

Example(s):

This example creates an infinite vertical band that remains "glued" to the viewport when the element is scrolled.

body { 
  background: red url("pendant.gif");
  background-repeat: repeat-y;
  background-attachment: fixed;
}

User agents may treat 'fixed' as 'scroll'. However, it is recommended they interpret 'fixed' correctly, at least for the HTML and BODY elements, since there is no way for an author to provide an image only for those browsers that support 'fixed'. See the section on conformance [add ref] for details.

3.5. The 'background-position' property

Name: background-position
Value: [ [<percentage> | <length> ]{1,2} | [ [top | center | bottom] || [left | center | right] ] ] | inherit
Initial: 0% 0%
Applies to: block-level and replaced elements
Inherited: no
Percentages: refer to the size of the box itself
Media: visual

Editor's Note: There is a question as to whether the computed value of this property should be 'length' or 'percentage'.

If a background image has been specified, this property specifies its initial position. Values have the following meanings:

<percentage> <percentage>
With a value pair of '0% 0%', the upper left corner of the image is aligned with the upper left corner of the box's padding edge. [modify; see 'background-origin'] A value pair of '100% 100%' places the lower right corner of the image in the lower right corner of padding area. With a value pair of '14% 84%', the point 14% across and 84% down the image is to be placed at the point 14% across and 84% down the padding area.
<length> <length>
With a value pair of '2cm 2cm', the upper left corner of the image is placed 2cm to the right and 2cm below the upper left corner of the padding area.
'top left' and 'left top'
Same as '0% 0%'.
'top', 'top center', and 'center top'
Same as '50% 0%'.
'right top' and 'top right'
Same as '100% 0%'.
'left', 'left center', and 'center left'
Same as '0% 50%'.
'center' and 'center center'
Same as '50% 50%'.
'right', 'right center', and 'center right'
Same as '100% 50%'.
'bottom left' and 'left bottom'
Same as '0% 100%'.
'bottom', 'bottom center', and 'center bottom'
Same as '50% 100%'.
'bottom right' and 'right bottom'
Same as '100% 100%'.

If only one percentage or length value is given, it sets the horizontal position only, the vertical position will be 50%. If two values are given, the horizontal position comes first. Combinations of length and percentage values are allowed, (e.g., '50% 2cm'). Negative positions are allowed. Keywords cannot be combined with percentage values or length values (all possible combinations are given above).

Example(s):

body { background: url("banner.jpeg") right top }    /* 100%   0% */
body { background: url("banner.jpeg") top center }   /*  50%   0% */
body { background: url("banner.jpeg") center }       /*  50%  50% */
body { background: url("banner.jpeg") bottom }       /*  50% 100% */

If the background image is fixed within the viewport (see the 'background-attachment' property), the image is placed relative to the viewport instead of the element's padding area. For example,

Example(s):

body { 
  background-image: url("logo.png");
  background-attachment: fixed;
  background-position: 100% 100%;
  background-repeat: no-repeat;
} 

In the example above, the (single) image is placed in the lower-right corner of the viewport.

3.6. The 'background-clip' property

Name: background-clip
Value: border | padding
Initial: border
Applies to: block-level and replaced elements
Inherited: no [yes?]
Percentages: N/A
Media: visual

Determines whether the background extents into the border area or not. If the value is 'padding', the background is clipped to the padding edge and the background of the border is transparent.

3.7. The 'background-origin' property

Name: background-origin
Value: border | padding | content
Initial: padding
Applies to: block-level and replaced elements
Inherited: no [yes?]
Percentages: N/A
Media: visual

Determines how the 'background-position' is calculated. With a value of 'padding', the position is relative to the padding edge ('0 0' is the upper left corner of the padding edge, 100% 100% is the lower right corner). 'Border' means the position is relative to the border edge, and 'content' means relative to the content edge.

Note that in CSS level 2, the position is always relative to the padding edge ('padding'), while in level 1 it is relative to the content edge ('content').

3.8. The 'background-size' property

Name: background-size
Value: [ <length> | <percentage> | auto ]{1,2}
Initial: auto
Applies to: all elements
Inherited: no
Percentages: see text
Media: visual

In case there is a 'background-image', the background-size can be used to stretch or shrink it.

If the property has only one value, it applies both horizontally and vertically. If there are two, the first one refers to the width, the second to the height of the background image. The values have the following meaning:

'auto'
The size that keeps the background image's original aspect ratio. Additionally, if the property's value is 'auto' or 'auto auto', the image has its intrinsic size.
<length>
A specific size.
<percentage>
This is only defined for block-level elements, for others it is equivalent to 'auto'. The percentage is relative to the width or height of the area given by 'background-origin'

Negative values are not allowed. A size of zero is allowed, but causes the image not to be displayed. (In particular, it will not be repeated.)

Here are some examples. The first example stretches the background image independently in both directions to completely cover the content area:

div {
    background-image: url(plasma.png);
    background-size: 100%;
    background-origin: content}

The second example stretches the image so that exactly two copies fit horizontally. The aspect ratio is preserved:

p {
    background-image: url(tubes.png);
    background-size: 50% auto;
    background-origin: border}

This example forces the background image to be 15 by 15 pixels:

para {
    background-size: 15px;
    background-image: url(tile.png)}

This example uses the image's intrinsic size. Note that this is the only possible behavior in CSS level 1 and 2.

body {
    background-size: auto;
    background-image: url(flower.png)}

3.9. The 'background-quantity' property

Name: background-quantity
Value: infinite | <integer> | inherit
Initial: infinite
Applies to: all elements
Inherited: no
Percentages: N/A
Media: visual

If a 'background-image' is specified, the value of 'background-quantity' determines how many times the image will repeat. Values for this property have the following meanings:

infinite: it specifies a continuous repetition of the background. If this parameter is set to "infinite", the image will repeat continuously.

integer: a numeric value that specifies how many times a background will repeat.

BODY {
      background-image: url(corazon.gif);
      background-repeat: repeat-x;
      background-quantity: 3;
      }

In the example above, the image will only repeat vertically three times.

Negative values are not allowed. The value zero means that the image is not rendered. The value one means the image will be repeated once.

3.10. The 'background- spacing' property

Name: background-spacing
Value: <length> | <length>? | inherit
Initial: 0
Applies to: all elements
Inherited: no
Percentages: N/A
Media: visual

This property specifies the distance that separates the 'background-image' of the position given by the property "background-position", as well as the spacing among all of the repetitions of the background image. If a measure is specified, this gives the horizontal and vertical space relative to the coordinates specified by the "background-position" property. The formatting model is as follows: (the left and top of the background-image) = background-origin + background-position + background-spacing

Values of this property have the following meanings: "length"-measure that indicates the spacing of the image with regard to initial position.

If only one value is specified, this gives the horizontal and vertical spacing. If two values are specified, the first value gives the horizontal spacing and the second gives the vertical spacing. Negative values are allowed, meaning that the image is aligned with its initial position, as well as negative measures being given for the repetitions.

Example:

BODY {
        background-image: url(chica.gif);
        background-repeat: repeat-x;
        background-quantity: 5;
        background-spacing: 10px 5px;
      }

3.11. The 'background' property

Name: background
Value: [<'background-color'> || <'background-image'> || <'background-repeat'> || <'background-attachment'> || <'background-position'>] [ / <'background-size'>]? | inherit
Initial: not defined for shorthand properties
Applies to: all elements
Inherited: no
Percentages: see 'background-position' and 'background-size'
Media: visual

The 'background' property is a shorthand property for setting several of the individual background properties at the same place in the style sheet.

The 'background' property first sets all the individual background properties for which it is a shorthand to their initial values, then assigns explicit values given in the declaration.

Example(s):

In the first rule of the following example, only a value for 'background-color' has been given and the other individual properties are set to their initial value. In the second rule, all individual properties have been specified.

body { background: red }
p { background: url("chess.png") gray 50% repeat fixed }

This example shows how a both a background color and a background image are set. The image is stretched to the full width of the element:

E {background: #CCC url("metal.jpg")/100% auto}

Note that 'background-clip' and 'background-origin' cannot be set with the 'background' shorthand.

4. Profiles

Each specification using W3C background functionality must define the subset of such functionality it allows and excludes, and describe the local meaning of all the components of that subset.

More information here in the future.

5. Conformance

This section will define conformance with the present specification only.

The inability of a user agent to implement part of this specification due to the limitations of a particular device does not imply non-conformance.

User agents must observe the rules for handling parsing errors.

6. Tests

This specification will contain a test suite allowing user agents to verify their basic conformance to the specification. This test suite does not pretend to be exhaustive and does not cover all possible combined cases of W3C background functionality.

7. Acknowledgements

This specification is the product of the W3C Working Group on Cascading Style Sheets and Formatting Properties. In addition to the editor of this specification, the members of the Working Group are:

A number of invited experts to the Working Group have significantly contributed to CSS 3 : David. L Baron, Todd Fahrner, Daniel Glazman, Ian Hickson, Eric Meyer (The OPAL Group), Jeff Veen.

Former members of the Working Group:

8. References

Normative references

[CSS3BOX]
Bert Bos. CSS3 module: box model. 26 July 2001. W3C working draft. (Work in progress.) URL: http://www.w3.org/TR/2001/WD-css3-box-20010726
[CSS3CASCADE]
Håkon Wium Lie. CSS3 module: Cascading and inheritance. 13 July 2001. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2001/WD-css3-cascade-20010713
[CSS3COLOR]
Tantek Çelik; Chris Lilley. CSS3 module: color. 5 March 2001. W3C working draft. (Work in progress.) URL: http://www.w3.org/TR/2001/WD-css3-color-20010305
[CSS3SYN]
David Baron. CSS3 module: syntax. (forthcoming). W3C working draft. (Work in progress.)
[CSS3VAL]
Håkon Wium Lie. CSS3 module: values and units. (forthcoming). W3C working draft. (Work in progress.)

Other references

[CSS1]
Håkon Wium Lie; Bert Bos. Cascading Style Sheets, level 1. 1996. W3C Recommendation. Revised 11 Jan 1999. URL: http://www.w3.org/TR/REC-CSS1
[CSS2]
Bert Bos; Håkon Wium Lie; Chris Lilley; Ian Jacobs. Cascading Style Sheets, level 2. 1998. W3C Recommendation. URL: http://www.w3.org/TR/REC-CSS2
[CSS3INTRO]
Eric A. Meyer; Bert Bos. Introduction to CSS3. 23 May 2001. W3C working draft. (Work in progress.) URL: http://www.w3.org/TR/css3-roadmap

Property index

Property Values Initial Applies to Inh. Percentages Media
background [<'background-color'> || <'background-image'> || <'background-repeat'> || <'background-attachment'> || <'background-position'>] [ / <'background-size'>]? | inherit not defined for shorthand properties all elements no see 'background-position' and 'background-size' visual
background-attachment scroll | fixed | inherit scroll all elements no N/A visual
background-clip border | padding border block-level and replaced elements no [yes?] N/A visual
background-color <color> | inherit transparent all elements no N/A visual
background-image <uri> | none | inherit none all elements no N/A visual
background-origin border | padding | content padding block-level and replaced elements no [yes?] N/A visual
background-position [ [<percentage> | <length> ]{1,2} | [ [top | center | bottom] || [left | center | right] ] ] | inherit 0% 0% block-level and replaced elements no refer to the size of the box itself visual
background-quantity infinite | <integer> | inherit infinite all elements no N/A visual
background-repeat repeat | repeat-x | repeat-y | no-repeat | inherit repeat all elements no N/A visual
background-size [ <length> | <percentage> | auto ]{1,2} auto all elements no see text visual
background-spacing <length> | <length>? | inherit 0 all elements no N/A visual