CSS Backgrounds Module Level 4

1. Introduction

When elements are rendered according to the CSS box model [CSS-BOX-3], each element is either not displayed at all, or formatted as one or more rectangular boxes. Each box has a rectangular content area, a band of padding around the content, a border around the padding, and a margin outside the border. (The margin may actually be negative, but margins have no influence on the background and border.)

The properties of this module deal with the background of the content, padding, and border areas.

If an element is broken into multiple box fragments, box-decoration-break defines how the borders and background are divided over the various fragments. (An element can result in more than one fragment if it is broken at the end of a line, at the end of a column or at the end of a page; and continued in the next line, column or page.)

The relative stacking order of backgrounds, borders, and shadows is given in this module. For how these layers interact with other rendered content, see Appendix E “Elaborate description of Stacking Contexts” in [CSS2].

1.1. Module Interactions

This specification extends the parts related to backgrounds of CSS Backgrounds and Borders Module Level 3 [CSS3BG].

It provides specifications for the added background-repeat-* and `background-position-*' longhands, a new background-tbd property that allows to define the background layers excluding the color, and adds two new values to background-clip.

All properties in this module apply to the ::first-letter and ::first-line pseudo-elements.

1.2. Value Definitions

This specification follows the CSS property definition conventions from [CSS2] using the value definition syntax from [CSS-VALUES-3]. Value types not defined in this specification are defined in CSS Values & Units [CSS-VALUES-3]. Combination with other CSS modules may expand the definitions of these value types. For example, combining with CSS Images allows for using CSS gradients as background-image or border-image values. [CSS-IMAGES-3]

In addition to the property-specific values listed in their definitions, all properties defined in this specification also accept the CSS-wide keywords as their property value. For readability they have not been repeated explicitly.

2. Defining Backgrounds

Each box has a background layer that may be fully transparent (the default), or filled with a color and/or one or more images. The background properties specify what color (background-color) and images (background-image) to use, and how they are sized, positioned, tiled, etc.

The 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.

2.1. Base Color: the background-color property

This property sets the background color of a box. This color is drawn behind any background images.

h1 { background-color: #F00 } /* Sets background to red. */

The background color is clipped according to the background-clip value associated with the bottom-most background image layer.

2.2. Image Sources: the background-image property

This property specifies the background image(s) of an element. Images are drawn with the first specified one on top (closest to the user) and each subsequent image behind the previous one. The property’s value is given as a comma-separated list of <bg-image> values where

<bg-image> = <image> | none

A value of none counts as a background image layer but draws nothing. An image that is empty (zero width or zero height), that fails to download, or that cannot be displayed (e.g., because it is not in a supported image format) likewise counts as a layer but draws nothing.

See § 3 Layering Multiple Background Images for how background-image interacts with other comma-separated background properties to form each background image layer.

When setting a background image, authors should also specify a background-color that will preserve contrast with the text for when the image is unavailable.

For accessibility reasons, authors should not use background images as the sole method of conveying important information. See Web Content Accessibility Guideline F3 [WCAG20]. Images are not accessible in non-graphical presentations, and background images specifically might be turned off in high-contrast display modes.

Note: Stylistic foreground images can be provided in CSS with the content property. Semantically-important foreground images should be provided in the document markup, e.g. with the <img> tag in HTML.

Note: Media fragments can be used to display a portion of an image. The CSS Images module will provide fallback syntax for image formats and include additional controls for image display.

html { background-image: url("marble.svg") }
p { background-image: none }
div { background-image: url(tl.png), url(tr.png) }
main { background-image: radial-gradient(at bottom right, transparent, white); }

Implementations may optimize by not downloading and drawing images that are not visible (e.g., because they are behind other, fully opaque images).

2.3. Tiling Images: the background-repeat-x, background-repeat-y, background-repeat-block, and background-repeat-inline properties

<repetition> = repeat | space | round | no-repeat

These properties specify whether and how background images are tiled along one axis after they have been sized and positioned.

repeat

The image is repeated in the given direction as often as needed to cover the background painting area.

space

The image is repeated in the given direction as often as will fit within the background positioning area without being clipped and then the repeated images are spaced out to fill the area. The first and last images touch the edges of the area. If the background painting area is larger than the background positioning area, then the pattern repeats to fill the background painting area. The value of background-position for this direction is ignored, unless there is not enough space for two copies of the image in this direction, in which case only one image is placed and background-position determines its position in this direction.

round

The image is repeated in the given direction as often as will fit within the background positioning area. If it doesn’t fit a whole number of times, it is rescaled so that it does. See the formula under background-size. If the background painting area is larger than the background positioning area, then the pattern repeats to fill the background painting area.

no-repeat

The image is placed once and not repeated in the given direction.

Unless one of the axes is set to no-repeat, the whole background painting area will be tiled, i.e., not just one vertical strip and one horizontal strip.

Example(s):

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

See the section § 3 Layering Multiple Background Images for how background-repeat-x, background-repeat-y, background-repeat-block, and background-repeat-inline interact with other comma-separated background properties to form each background image layer.

2.4. Tiling Images Shorthand: the background-repeat property

This shorthand sets the values for the background-repeat-x and background-repeat-y longhand properties.

<repeat-style> = repeat-x | repeat-y | repeat-block | repeat-inline | <repetition>{1,2}

Single values for <repeat-style> have the following meanings:

repeat-x

Computes to repeat no-repeat.

repeat-y

Computes to no-repeat repeat.

repeat-block

Computes to repeat in the block axis and no-repeat in the inline axis.

repeat-inline

Computes to repeat in the inline axis and no-repeat in the block axis.

repeat

Computes to repeat repeat.

space

Computes to space space

round

Computes to round round

no-repeat

Computes to no-repeat no-repeat

If a <repeat-style> value has two keywords, the first one is for the horizontal direction, the second for the vertical one.

Example(s):

body {
  background-image: url(dot.png) white;
  background-repeat: space;
}

See the section § 3 Layering Multiple Background Images for how background-repeat interacts with other comma-separated background properties to form each background image layer.

Should a 'background-repeat: extend' be added?

2.5. Affixing Images: the background-attachment property

If background images are specified, this property specifies whether they are fixed with regard to the viewport (fixed) or scroll along with the box (scroll) or its contents (local). The property’s value is given as a comma-separated list of <attachment> keywords where

<attachment> = scroll | fixed | local

fixed

The background is fixed with regard to the viewport. In paged media where there is no viewport, a fixed background is fixed with respect to the page box and therefore replicated on every page.

Note: There is only one viewport per view. Even if an box is a scroll container, a fixed background doesn’t move with the box.

local

The background is fixed with regard to the box’s contents: if the box is a scroll container, the background scrolls with the box’s contents, and the background painting area and background positioning area are relative to the scrollable overflow area of the box rather than to the border framing them. Because the scrollable overflow area does not include the border area, for scroll containers the border-box value of background-clip may be treated the same as padding-box.

scroll

The background is fixed with regard to the box itself and does not scroll with its contents. (It is effectively attached to the box’s border.)

Even if the image is fixed, it is still only visible when it is in the background painting area of the box or otherwise unclipped. (See § 4 Backgrounds of Special Elements for the cases when background images are not clipped.) Thus, unless the image is tiled, it may be invisible.

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

Note: User agents that do not support fixed backgrounds (for example due to limitations of the hardware platform) will ignore declarations with the keyword fixed. For example:

body {
  /* For all UAs: */
  background: white url(paper.png) scroll;
  /* For UAs that do fixed backgrounds: */
  background: white url(ledger.png) fixed;
}
h1 {
  /* For all UAs: */
  background: silver;
  /* For UAs that do fixed backgrounds: */
  background: url(stripe.png) fixed, white url(ledger.png) fixed;
}

See § 3 Layering Multiple Background Images for how background-attachment interacts with other comma-separated background properties to form each background image layer.

2.6. Background Positioning: the background-position-x, background-position-y, background-position-inline, and background-position-block properties

This section is still being worked out. The tricky thing is making all the start/end keywords work sanely.

This property specifies the background position’s horizontal component. An omitted origin keyword is assumed to be left.

This property specifies the background position’s vertical component. An omitted origin keyword is assumed to be top.

This property specifies the background position’s inline-axis component. An omitted origin keyword is assumed to be start.

This property specifies the background position’s block-axis component. An omitted origin keyword is assumed to be start.

<percentage>

A percentage for the horizontal offset is relative to (width of background positioning area - width of background image). A percentage for the vertical offset is relative to (height of background positioning area - height of background image), where the size of the image is the size given by background-size.

For example, with a value pair of 0% 0%, the upper left corner of the image is aligned with the upper left corner of, usually, the box’s padding edge. A value pair of 100% 100% places the lower right corner of the image in the lower right corner of the area. With a value pair of 75% 50%, the point 75% across and 50% down the image is to be placed at the point 75% across and 50% down the area.

<length>

A length value gives a fixed length as the offset. For example, with a value pair of 2cm 1cm, the upper left corner of the image is placed 2cm to the right and 1cm below the upper left corner of the background positioning area.