diff --git a/css-backgrounds-4/Overview.bs b/css-backgrounds-4/Overview.bs index 20319632832..735dbeb1bfb 100644 --- a/css-backgrounds-4/Overview.bs +++ b/css-backgrounds-4/Overview.bs @@ -11,7 +11,10 @@ Editor: Elika J. Etemad / fantasai, Apple, http://fantasai.inkedblade.net/contac Editor: Lea Verou, Invited Expert, http://lea.verou.me/about/, w3cid 52258 Editor: Sebastian Zartner, Invited Expert, sebastianzartner@gmail.com, w3cid 64937 Abstract: This module contains the features of CSS relating to the backgrounds of boxes on the page. +Ignored Vars: width of background positioning area, width of background image, height of background positioning area, height of background image, X' Ignored Terms: total width +WPT Path Prefix: css/css-backgrounds/ +WPT Display: closed Warning: Not Ready @@ -19,9 +22,15 @@ Warning: Not Ready spec:css-text-4; type:value; text:collapse spec:css-shapes-2; type:function; text:path() spec:css-borders-4; + type:property; text:border type:property; text:border-color + type:property; text:border-image + type:property; text:border-radius type:property; text:border-style type:property; text:border-width + type:property; text:box-shadow +spec:css2; type:dfn; text:viewport +spec:html; type:element; text:body @@ -29,16 +38,287 @@ spec:css-borders-4;

Introduction

-

- This module is currently maintained as a diff against - the parts related to backgrounds of - CSS Backgrounds and Borders Module Level 3 [[CSS3BG]]. - We will fold in the text once it's all formatted up and in CR again, - as this will reduce the effort of keeping them in sync - (source diffs will be accurate in reflecting the differences). + 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.) + +

+ Diagram of a typical box, showing the content, padding, border and margin areas + +
+ The various areas and edges of a typical box. + (This diagram is explained in the CSS Box Model Module [[!CSS-BOX-3]].) +
+
+ + The properties of this module deal with the background of the [=content area|content=], [=padding area|padding=], and [=border area|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]]. + +

+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=]. + +

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

-Backgrounds

+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'. + +

+Base Color: the 'background-color' property

+ +
+	Name: background-color
+	Value: <>
+	Initial: transparent
+	Applies to: all elements
+	Inherited: no
+	Percentages: N/A
+	Computed value: computed color
+	Animation type: by computed value
+	
+ + + animations/background-color-animation-backdrop-infinite-duration-crash.html + animations/background-color-animation-custom-property.html + animations/background-color-animation-custom-timing-function-reverse.html + animations/background-color-animation-custom-timing-function.html + animations/background-color-animation-element-not-visible-at-current-viewport.html + animations/background-color-animation-fallback-additive-keyframe.html + animations/background-color-animation-fallback-missing-0-percent.html + animations/background-color-animation-fallback-missing-100-percent.html + animations/background-color-animation-fallback-replace.html + animations/background-color-animation-field-crash.html + animations/background-color-animation-fragmented.html + animations/background-color-animation-half-opaque.html + animations/background-color-animation-in-body.html + animations/background-color-animation-non-empty-no-draw-crash.html + animations/background-color-animation-non-zero-size-element-change-to-zero.html + animations/background-color-animation-pseudo-element.html + animations/background-color-animation-removed-element-crash.html + animations/background-color-animation-single-keyframe.html + animations/background-color-animation-three-keyframes1.html + animations/background-color-animation-three-keyframes2.html + animations/background-color-animation-three-keyframes3.html + animations/background-color-animation-will-change-contents.html + animations/background-color-animation-with-blur.html + animations/background-color-animation-with-images.html + animations/background-color-animation-with-mask.html + animations/background-color-animation-with-table1.html + animations/background-color-animation-with-table2.html + animations/background-color-animation-with-table3.html + animations/background-color-animation-with-table4.html + animations/background-color-animation-with-zero-playbackRate.html + animations/background-color-animation-zero-size-element-change-to-non-zero.html + animations/background-color-animation-zero-size-element.html + animations/background-color-animation.html + animations/background-color-interpolation.html + animations/background-color-scroll-into-viewport.html + animations/background-color-transition-colormix.html + animations/background-color-transition-currentcolor.html + animations/background-color-transition.html + animations/background-color-transparent-animation-in-body.html + animations/invalidation/background-color-animation-with-zero-alpha.html + animations/invalidation/background-color-transition-obscured.html + animations/invalidation/background-color-transition-with-delay.html + animations/invalidation/background-color-transition-with-initially-transparent.html + animations/two-background-color-animation-diff-length1.html + animations/two-background-color-animation-diff-length2.html + animations/two-background-color-animation-diff-length3.html + background-none-none-and-color.html + background-color-body-propagation-001.html + background-color-body-propagation-002.html + background-color-body-propagation-003.html + background-color-body-propagation-004.html + background-color-body-propagation-005.html + background-color-body-propagation-006.html + background-color-body-propagation-007.html + background-color-body-propagation-008.html + background-color-body-propagation-009.html + background-color-clip.html + background-color-root-propagation-001.html + background-color-root-propagation-002.html + bg-color-with-gradient.html + child-move-reveals-parent-background.html + color-mix-currentcolor-background-repaint-parent.html + color-mix-currentcolor-background-repaint.html + hidpi/simple-bg-color.html + inheritance.sub.html + inline-background-rtl-001.html + parsing/background-color-computed.html + parsing/background-color-invalid.html + parsing/background-color-valid.html + color-behind-images.htm + + + This property sets the background color of a box. + This color is drawn behind any background images. + +
+ Example: + +
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=]. + +

+Image Sources: the 'background-image' property

+ +
+	Name: background-image
+	Value: <>#
+	Initial: none
+	Applies to: all elements
+	Inherited: no
+	Percentages: N/A
+	Computed value: list, each item either an <> or the keyword ''background-image/none''
+	Animation type: discrete
+	
+ + + background-image-001.html + background-image-002.html + background-image-003.html + background-image-004.html + background-image-005.html + background-image-006.html + background-image-007.html + background-image-centered-with-border-radius.html + background-image-centered.html + background-image-cors-no-reload.html + background-image-cover-zoomed-1.html + background-image-first-letter.html + background-image-first-line.html + background-image-gradient-currentcolor-conic-repaint.html + background-image-gradient-currentcolor-linear-repaint.html + background-image-gradient-currentcolor-radial-repaint.html + background-image-gradient-currentcolor-visited.html + background-image-gradient-interpolation-repaint.html + background-image-large-with-auto.html + background-image-none-gradient-repaint.html + background-image-shared-stylesheet.html + background-image-table-cells-straddling-no-repeat.html + background-image-table-cells-zoomed.html + background-image-with-border-radius-fidelity.html + animations/background-image-interpolation.html + inheritance.sub.html + parsing/background-image-computed.sub.html + parsing/background-image-invalid.html + parsing/background-image-valid.html + + + 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 <> values where + +
<> = <> | 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 [[#layering]] 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. + +
+ Some examples specifying background images: + +
+		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).

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

@@ -96,18 +376,19 @@ Tiling Images: the 'background-repeat-x', 'background-repeat-y', 'background-rep 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. +

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;
-			}
+		body {
+			background: white url("pendant.png");
+			background-repeat-y: repeat;
+			background-position: center;
+		}
 		
@@ -121,8 +402,7 @@ Tiling Images: the 'background-repeat-x', 'background-repeat-y', 'background-rep
-

See the section “Layering multiple background - images” for how +

See the section [[#layering]] for how 'background-repeat-x', 'background-repeat-y', 'background-repeat-block', @@ -144,10 +424,48 @@ Tiling Images Shorthand: the 'background-repeat' property Animation type: discrete + + animations/discrete-no-interpolation.html + background-repeat-round-1a.html + background-repeat-round-1b.html + background-repeat-round-1c.html + background-repeat-round-1d.html + background-repeat-round-1e.html + background-repeat-round-2.html + background-repeat-round-3.html + background-repeat-round-4.html + background-repeat-space-10.html + background-repeat-space-1a.html + background-repeat-space-1b.html + background-repeat-space-1c.html + background-repeat-space-2.html + background-repeat-space-3.html + background-repeat-space-4.html + background-repeat-space-5.html + background-repeat-space-6.html + background-repeat-space-7.html + background-repeat-space-8.html + background-repeat-space-9.html + background-repeat/background-repeat-no-repeat.xht + background-repeat/background-repeat-repeat-x.xht + background-repeat/background-repeat-repeat-y.xht + background-repeat/background-repeat-round-roundup.xht + background-repeat/background-repeat-round.xht + background-repeat/background-repeat-space.xht + background-repeat/gradient-repeat-spaced-with-borders.html + inheritance.sub.html + parsing/background-repeat-computed.html + parsing/background-repeat-invalid.html + parsing/background-repeat-valid.html + subpixel-repeat-no-repeat-mix.html + +

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

<> = repeat-x | repeat-y | <>{1,2}
+ +
+		<> = repeat-x | repeat-y | <>{1,2}
+	

Single values for <> have the following meanings: @@ -178,82 +496,179 @@ Tiling Images Shorthand: the 'background-repeat' property Computes to ''no-repeat no-repeat'' -

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

If a <> 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
-	}
-	
+
+

Example(s): -

-

Image of an element with a dotted background +

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

The effect of ''background-repeat/space'': the image of a dot is - tiled to cover the whole background and the images are equally - spaced. -

+
+

Image of an element with a dotted background + +

The effect of ''background-repeat/space'': the image of a dot is + tiled to cover the whole background and the images are equally + spaced. +

-

See the section “Layering multiple background - images” for how 'background-repeat' interacts with other +

See the section [[#layering]] for how 'background-repeat' interacts with other comma-separated background properties to form each background image layer. Issue: Should a 'background-repeat: extend' be added? -

-Background Positioning: the 'background-position' shorthand property

+

+Affixing Images: the 'background-attachment' property

-	Name: background-position
-	Value: <>#
-	Initial: 0% 0%
+	Name: background-attachment
+	Value: <>#
+	Initial: scroll
 	Applies to: all elements
 	Inherited: no
-	Percentages: refer to size of background positioning area
-	    minus size of background image; see text
-	Computed value: a list,
-	    each item a pair of offsets (horizontal and vertical) from the top left origin,
-	    each offset given as a computed <> value
-	Animation type: repeatable list
+	Percentages: N/A
+	Computed value: list, each item the keyword as specified
+	Animation type: discrete
 	
- If [=background images=] have been specified, - this property specifies their initial position - (after any resizing) - within their corresponding [=background positioning area=]. + + animations/discrete-no-interpolation.html + background-attachment-350.html + background-attachment-353.html + background-attachment-fixed-block-002.html + background-attachment-fixed-border-radius-offset.html + background-attachment-fixed-inline-002.html + background-attachment-fixed-inline-scrolled.html + background-attachment-fixed-inside-transform-1.html + background-attachment-local-block-002.html + background-attachment-local-hidden.html + background-attachment-local/attachment-local-clipping-color-1.html + background-attachment-local/attachment-local-clipping-color-2.html + background-attachment-local/attachment-local-clipping-color-3.html + background-attachment-local/attachment-local-clipping-color-4.html + background-attachment-local/attachment-local-clipping-color-5.html + background-attachment-local/attachment-local-clipping-color-6.html + background-attachment-local/attachment-local-clipping-image-1.html + background-attachment-local/attachment-local-clipping-image-2.html + background-attachment-local/attachment-local-clipping-image-3.html + background-attachment-local/attachment-local-clipping-image-4.html + background-attachment-local/attachment-local-clipping-image-5.html + background-attachment-local/attachment-local-clipping-image-6.html + background-attachment-local/attachment-local-positioning-2.html + background-attachment-local/attachment-local-positioning-3.html + background-attachment-local/attachment-local-positioning-4.html + background-attachment-local/attachment-local-positioning-5.html + background-attachment-local/attachment-scroll-positioning-1.html + background-attachment-margin-root-001.html + background-attachment-margin-root-002.html + inheritance.sub.html + local-attachment-content-box-scroll.html + parsing/background-attachment-computed.html + parsing/background-attachment-invalid.html + parsing/background-attachment-valid.html + table-cell-background-local-002.html + table-cell-background-local-003.html + table-cell-background-local.html + + + 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 <> keywords where + +
<> = 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 has a scrolling mechanism, + 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 ''background-clip/border-box'' value of 'background-clip' + may be treated the same as ''background-clip/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.) +
- This property is a [=shorthand property=] that sets - 'background-position-x', 'background-position-y', 'background-position-block', and 'background-position-inline' - in a single declaration. + 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 [[#special-backgrounds]] for the cases when + background images are not clipped.) + Thus, unless the image is tiled, it may be invisible. - Its value is given as a comma-separated list - of <> values, which are interpreted as <> values - with the resized [=background image=] as the [=alignment subject=] - and the [=background positioning area=] as the [=alignment container=]. +
+ This example creates an infinite vertical band + that remains “glued” to the viewport when the document is scrolled. -
-		<> =  <> | <>
-		<> = [
-		  [ left | center | right ] && [ [ top | bottom ] <> ]
-		|
-		  [ [ left | right ] <> ] && [ top | center | bottom ]
-		]
-	
+
+		body {
+			background: red url("pendant.gif");
+			background-repeat: repeat-y;
+			background-attachment: fixed;
+		}
+		
+
- The omitted <> in the 'background-position'-specific - <> syntax variant - defaults to ''0%''. + 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: - Issue(9690): Specify how the [=longhand properties=] are set. +
+	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 [[#layering]] for how 'background-attachment' interacts + with other comma-separated background properties + to form each [=background image layer=]. -

-Background Positioning Longhands: the 'background-position-x', 'background-position-y', 'background-position-inline', and 'background-position-block' properties

+

+Background Positioning: the 'background-position-x', 'background-position-y', 'background-position-inline', and 'background-position-block' properties

Issue: This section is still being worked out. The tricky thing is making all the start/end keywords work sanely. @@ -313,6 +728,223 @@ Background Positioning Longhands: the 'background-position-x', 'background-posit This property specifies the background position's block-axis component. An omitted origin keyword is assumed to be ''background-position-block/start''. +
+
<> +
+ 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. + +
+ Diagram of image position within element +
+ Diagram of the meaning of ''background-position: 75% 50%''. +
+
+
+ +
<> +
+ 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=]. + +
''top'' +
+ Computes to ''0%'' for the vertical position if one or two values are given, + otherwise specifies the top edge as the origin for the next offset. + +
''right'' +
+ Computes to ''100%'' for the horizontal position if one or two values are given, + otherwise specifies the right edge as the origin for the next offset. + +
''bottom'' +
+ Computes to ''100%'' for the vertical position if one or two values are given, + otherwise specifies the bottom edge as the origin for the next offset. + +
''left'' +
+ Computes to ''0%'' for the horizontal position if one or two values are given, + otherwise specifies the left edge as the origin for the next offset. + +
''center'' +
+ Computes to ''50%'' (''left 50%'') for the horizontal position + if the horizontal position is not otherwise specified, + or ''50%'' (''top 50%'') for the vertical position if it is. +
+ +
+ The following 'background' shorthand declarations use keywords + to set 'background-position' to the stated percentage values. + +
+		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% */
+		
+
+ +
+ In the example below, the (single) image is placed + in the lower-right corner of the viewport. + +
+		body {
+			background-image: url("logo.png");
+			background-attachment: fixed;
+			background-position: 100% 100%;
+			background-repeat: no-repeat;
+		}
+		
+
+ +
+ Background positions can also be relative to other corners than the top left. + For example, the following puts the background image + 10px from the bottom and 3em from the right: + +
background-position: right 3em bottom 10px
+
+ + See [[#layering]] for how 'background-position' interacts + with other comma-separated background properties + to form each [=background image layer=]. + +

+Background Positioning Shorthand: the 'background-position' shorthand property

+ +
+	Name: background-position
+	Value: <>#
+	Initial: 0% 0%
+	Applies to: all elements
+	Inherited: no
+	Percentages: refer to size of background positioning area
+	    minus size of background image; see text
+	Computed value: a list,
+	    each item a pair of offsets (horizontal and vertical) from the top left origin,
+	    each offset given as a computed <> value
+	Animation type: repeatable list
+	
+ + + animations/background-position-interpolation.html + animations/background-position-x-interpolation.html + animations/background-position-y-interpolation.html + background-position-calc-minmax-001.html + background-position-negative-percentage-comparison-002.html + background-position-negative-percentage-comparison.html + background-position-three-four-values.html + background-position-xy-three-four-values-passthru.html + background-position/background-position-bottom-right-repeat-round.html + background-position/background-position-right-in-body.html + inheritance.sub.html + parsing/background-position-computed.html + parsing/background-position-invalid.html + parsing/background-position-valid.html + parsing/background-position-x-computed.html + parsing/background-position-x-invalid.html + parsing/background-position-x-valid.html + parsing/background-position-y-computed.html + parsing/background-position-y-invalid.html + parsing/background-position-y-valid.html + + + If [=background images=] have been specified, + this property specifies their initial position + (after any resizing) + within their corresponding [=background positioning area=]. + + This property is a [=shorthand property=] that sets + 'background-position-x', 'background-position-y', 'background-position-block', and 'background-position-inline' + in a single declaration. + + Its value is given as a comma-separated list + of <> values, which are interpreted as <> values + with the resized [=background image=] as the [=alignment subject=] + and the [=background positioning area=] as the [=alignment container=]. + + Note: A pair of keywords can be reordered, + while a combination of keyword and length or percentage cannot. + So ''center left'' is valid while ''50% left'' is not. + + If three or four values are given, + then each <> represents an offset + and must be preceded by a keyword, + which specifies from which edge the offset is given. + For example, ''background-position: bottom 10px right 20px'' + represents a ''10px'' vertical offset up from the bottom edge + and a ''20px'' horizontal offset leftward from the right edge. + If three values are given, + the missing offset is assumed to be zero. + + Positive values represent an offset inward + from the edge of the [=background positioning area=]. + Negative values represent an offset outward + from the edge of the [=background positioning area=]. + +
+ The following declarations give the stated (horizontal, vertical) + offsets from the top left corner: + +
+		background-position: left 10px top 15px;   /* 10px, 15px */
+		background-position: left      top     ;   /*  0px,  0px */
+		background-position:      10px     15px;   /* 10px, 15px */
+		background-position: left          15px;   /*  0px, 15px */
+		background-position:      10px top     ;   /* 10px,  0px */
+		background-position: left      top 15px;   /*  0px, 15px */
+		background-position: left 10px top     ;   /* 10px,  0px */
+		
+
+ +
+		<> =  <> | <>
+		<> = [
+		  [ left | center | right ] && [ [ top | bottom ] <> ]
+		|
+		  [ [ left | right ] <> ] && [ top | center | bottom ]
+		]
+	
+ + The omitted <> in the 'background-position'-specific + <> syntax variant + defaults to ''0%''. + + Issue(9690): Specify how the [=longhand properties=] are set. + +

+Serialization of 'background-position' values

+ + The [=specified value=] and [=computed value=] of the <> type + serialize exactly as defined in [[CSS-VALUES-4]] for <>. + For 3-value productions + (which are not valid in <>), + the [=specified value=] serialization + is identical to the equivalent 4-value syntax + except that the omitted offset remains omitted. +

Painting Area: the 'background-clip' property

@@ -324,6 +956,63 @@ Painting Area: the 'background-clip' property Animation type: repeatable list + + animations/discrete-no-interpolation.html + background-clip-001.html + background-clip-002.html + background-clip-003.html + background-clip-004.html + background-clip-005.html + background-clip-006.html + background-clip-007.html + background-clip-008.html + background-clip-009.html + background-clip-010.html + background-clip-color-repaint.html + background-clip-color.html + background-clip-content-box-001.html + background-clip-content-box-002.html + background-clip-padding-box-001.html + background-clip-padding-box-with-border-radius.html + background-clip-content-box-with-border-radius-002.html + background-clip-content-box-with-border-radius-003.html + background-clip-padding-box-with-border-radius-002.html + background-clip-padding-box-with-border-radius-003.html + background-clip/clip-border-area-background-geometry.html + background-clip/clip-border-area-border-on-top.html + background-clip/clip-border-area-border-image.html + background-clip/clip-border-area-box-decoration-break.html + background-clip/clip-border-area-multiple-backgrounds.html + background-clip/clip-border-area-on-body-not-propagated-to-root.html + background-clip/clip-border-area-on-body-propagated-to-root.html + background-clip/clip-border-area-on-root.html + background-clip/clip-border-area.html + background-clip/clip-rounded-corner.html + background-clip/clip-text-ellipsis.html + background-clip/clip-text-animated-text.html + background-clip/clip-text-dynamic-2.html + background-clip/clip-text-flex.html + background-clip/clip-text-multi-line.html + background-clip/clip-text-on-body-not-propagated-to-root.html + background-clip/clip-text-on-body-propagated-to-root.html + background-clip/clip-text-on-root.html + background-clip/clip-text-text-decorations.html + background-clip/clip-text-text-emphasis.html + background-clip_padding-box.html + background-paint-order-001.html + background-rounded-image-clip-001.html + background-rounded-image-clip-002.html + css3-background-clip-border-box.html + css3-background-clip-content-box.html + css3-background-clip-padding-box.html + css3-background-clip.html + inheritance.sub.html + local-attachment-content-box-scroll.html + parsing/background-clip-computed.html + parsing/background-clip-invalid.html + parsing/background-clip-valid.html + + Determines the background painting area, which determines the area within which the background is painted. The syntax of the property is given with @@ -350,13 +1039,600 @@ Painting Area: the 'background-clip' property
border-area
- The background is clipped to the area painted by the border, taking 'border-width' and 'border-style' into account but ignoring any transparency introduced by 'border-color'. + The background is clipped to the area painted by the border, + taking 'border-width' and 'border-style' into account but ignoring any transparency introduced by 'border-color'.
If both ''background-clip/border-area'' and ''background-clip/text'' are specified, the background is painted within (clipped to) the union of these two areas. + Note: The root element has a different [=background painting area=] + and thus the 'background-clip' property has no effect when specified on it. + See [[#special-backgrounds]]. + + Note: The background is always drawn behind the border, if any. + See “Elaborate description of Stacking Contexts” in [[!CSS2]] Appendix E. + + See [[css-borders-4#corner-shaping]] for how 'border-radius' affects + the shape of the [=background painting area=]. + + See [[#layering]] for how 'background-clip' interacts + with other comma-separated background properties + to form each [=background image layer=]. + +

+Positioning Area: the 'background-origin' property

+ +
+	Name: background-origin
+	Value: <>#
+	Initial: padding-box
+	Applies to: all elements
+	Inherited: no
+	Percentages: N/A
+	Computed value: list, each item a keyword as specified
+	Animation type: repeatable list
+	
+ + + animations/discrete-no-interpolation.html + animations/background-position-origin-interpolation.html + background-gradient-subpixel-fills-area.html + background-origin-001.html + background-origin-002.html + background-origin-003.html + background-origin-004.html + background-origin-005.html + background-origin-006.html + background-origin-007.html + background-origin-008.html + background-origin/origin-border-box.html + background-origin/origin-border-box_with_position.html + background-origin/origin-border-box_with_radius.html + background-origin/origin-border-box_with_size.html + background-origin/origin-content-box.html + background-origin/origin-content-box_with_position.html + background-origin/origin-content-box_with_radius.html + background-origin/origin-content-box_with_size.html + background-origin/origin-padding-box.html + background-origin/origin-padding-box_with_position.html + background-origin/origin-padding-box_with_radius.html + background-origin/origin-padding-box_with_size.html + css3-background-origin-border-box.html + css3-background-origin-content-box.html + css3-background-origin-padding-box.html + inheritance.sub.html + parsing/background-origin-computed.html + parsing/background-origin-invalid.html + parsing/background-origin-valid.html + + + This property determines the background positioning area: + the area within which any background images are positioned. + For elements rendered as multiple [=box fragments=] + (e.g., inline boxes on several lines, boxes on several pages), + specifies which boxes 'box-decoration-break' [[CSS-BREAK-3]] operates on + to determine the background positioning area(s). + +
+
padding-box +
+ The position is relative to the [=padding box=]. + (For single boxes ''0 0'' is the upper left corner of the padding edge, + ''100% 100%'' is the lower right corner.) +
border-box +
+ The position is relative to the [=border box=]. +
content-box +
+ The position is relative to the [=content box=]. +
+ + If the 'background-attachment' value for this [=layer=] is ''fixed'', + then this property has no effect: + in this case the [=background positioning area=] is + the [=initial containing block=]. + + Note: If 'background-clip' is ''background-clip/padding-box'', + 'background-origin' is ''background-origin/border-box'', + 'background-position' is ''top left'' (the initial value), + and the element has a non-zero border, + then the top and left edges of the [=background image=] will be clipped. + + See [[#layering]] for how 'background-origin' interacts + with other comma-separated background properties + to form each [=background image layer=]. + +

+Sizing Images: the 'background-size' property

+ +
+	Name: background-size
+	Value: <>#
+	Initial: auto
+	Applies to: all elements
+	Inherited: no
+	Percentages: see text
+	Computed value: list,
+		each item a pair of sizes (one per axis)
+		each represented as either a keyword or a computed <> value
+	Animation type: repeatable list
+	
+ + + animations/background-size-interpolation.html + background-size-001.html + background-size-002.html + background-size-005.html + background-size-006.html + background-size-007.html + background-size-008.html + background-size-009.html + background-size-010.html + background-size-011.html + background-size-012.html + background-size-013.html + background-size-014.html + background-size-015.html + background-size-016.html + background-size-017.html + background-size-018.html + background-size-019.html + background-size-020.html + background-size-021.html + background-size-025.html + background-size-026.html + background-size-027.html + background-size-028.html + background-size-029.html + background-size-030.html + background-size-031.html + background-size-034.html + background-size-041.html + background-size-042.html + background-size-043.html + background-size-044.html + background-size-contain-001.html + background-size-contain-002.html + background-size-cover-001.html + background-size-cover-002.html + background-size-cover-003.html + background-size-one-value-1x1-image.html + background-size-percentage-root.html + background-size-with-negative-value.html + background-size/background-size-contain-svg-view.html + background-size/background-size-contain.xht + background-size/background-size-cover-contain-001.xht + background-size/background-size-cover-contain-002.xht + background-size/background-size-cover-svg-view.html + background-size/background-size-cover-svg.html + background-size/background-size-cover.xht + background-size/background-size-near-zero-color.html + background-size/background-size-near-zero-gradient.html + background-size/background-size-near-zero-png.html + background-size/background-size-near-zero-svg.html + background-size/vector/background-size-vector-001.html + background-size/vector/background-size-vector-002.html + background-size/vector/background-size-vector-003.html + background-size/vector/background-size-vector-004.html + background-size/vector/background-size-vector-005.html + background-size/vector/background-size-vector-006.html + background-size/vector/background-size-vector-007.html + background-size/vector/background-size-vector-008.html + background-size/vector/background-size-vector-009.html + background-size/vector/background-size-vector-010.html + background-size/vector/background-size-vector-011.html + background-size/vector/background-size-vector-012.html + background-size/vector/background-size-vector-013.html + background-size/vector/background-size-vector-014.html + background-size/vector/background-size-vector-015.html + background-size/vector/background-size-vector-016.html + background-size/vector/background-size-vector-017.html + background-size/vector/background-size-vector-018.html + background-size/vector/background-size-vector-019.html + background-size/vector/background-size-vector-020.html + background-size/vector/background-size-vector-021.html + background-size/vector/background-size-vector-022.html + background-size/vector/background-size-vector-023.html + background-size/vector/background-size-vector-024.html + background-size/vector/background-size-vector-025.html + background-size/vector/background-size-vector-026.html + background-size/vector/background-size-vector-027.html + background-size/vector/background-size-vector-028.html + background-size/vector/background-size-vector-029.html + background-size/vector/diagonal-percentage-vector-background.html + background-size/vector/tall--auto--omitted-width-percent-height.html + background-size/vector/tall--auto--percent-width-nonpercent-height-viewbox.html + background-size/vector/tall--auto--percent-width-nonpercent-height.html + background-size/vector/tall--auto--percent-width-omitted-height-viewbox.html + background-size/vector/tall--auto--percent-width-omitted-height.html + background-size/vector/tall--auto--percent-width-percent-height-viewbox.html + background-size/vector/tall--auto--percent-width-percent-height.html + background-size/vector/tall--auto-32px--nonpercent-width-nonpercent-height-viewbox.html + background-size/vector/tall--auto-32px--nonpercent-width-nonpercent-height.html + background-size/vector/tall--auto-32px--nonpercent-width-omitted-height-viewbox.html + background-size/vector/tall--auto-32px--nonpercent-width-omitted-height.html + background-size/vector/tall--auto-32px--nonpercent-width-percent-height-viewbox.html + background-size/vector/tall--auto-32px--nonpercent-width-percent-height.html + background-size/vector/tall--auto-32px--omitted-width-nonpercent-height-viewbox.html + background-size/vector/tall--auto-32px--omitted-width-nonpercent-height.html + background-size/vector/tall--auto-32px--omitted-width-omitted-height-viewbox.html + background-size/vector/tall--auto-32px--omitted-width-omitted-height.html + background-size/vector/tall--auto-32px--omitted-width-percent-height-viewbox.html + background-size/vector/tall--auto-32px--omitted-width-percent-height.html + background-size/vector/tall--auto-32px--percent-width-nonpercent-height-viewbox.html + background-size/vector/tall--auto-32px--percent-width-nonpercent-height.html + background-size/vector/tall--auto-32px--percent-width-omitted-height-viewbox.html + background-size/vector/tall--auto-32px--percent-width-omitted-height.html + background-size/vector/tall--auto-32px--percent-width-percent-height-viewbox.html + background-size/vector/tall--auto-32px--percent-width-percent-height.html + background-size/vector/tall--contain--height.html + background-size/vector/tall--contain--nonpercent-width-nonpercent-height-viewbox.html + background-size/vector/tall--contain--nonpercent-width-nonpercent-height.html + background-size/vector/tall--contain--nonpercent-width-omitted-height-viewbox.html + background-size/vector/tall--contain--nonpercent-width-omitted-height.html + background-size/vector/tall--contain--nonpercent-width-percent-height-viewbox.html + background-size/vector/tall--contain--nonpercent-width-percent-height.html + background-size/vector/tall--contain--omitted-width-nonpercent-height-viewbox.html + background-size/vector/tall--contain--omitted-width-nonpercent-height.html + background-size/vector/tall--contain--omitted-width-omitted-height-viewbox.html + background-size/vector/tall--contain--omitted-width-omitted-height.html + background-size/vector/tall--contain--omitted-width-percent-height-viewbox.html + background-size/vector/tall--contain--omitted-width-percent-height.html + background-size/vector/tall--contain--percent-width-nonpercent-height-viewbox.html + background-size/vector/tall--contain--percent-width-nonpercent-height.html + background-size/vector/tall--contain--percent-width-omitted-height-viewbox.html + background-size/vector/tall--contain--percent-width-omitted-height.html + background-size/vector/tall--contain--percent-width-percent-height-viewbox.html + background-size/vector/tall--contain--percent-width-percent-height.html + background-size/vector/tall--contain--width.html + background-size/vector/tall--cover--height.html + background-size/vector/tall--cover--nonpercent-width-nonpercent-height--crisp.html + background-size/vector/tall--cover--nonpercent-width-nonpercent-height-viewbox--crisp.html + background-size/vector/tall--cover--nonpercent-width-nonpercent-height-viewbox.html + background-size/vector/tall--cover--nonpercent-width-nonpercent-height.html + background-size/vector/tall--cover--nonpercent-width-omitted-height-viewbox.html + background-size/vector/tall--cover--nonpercent-width-omitted-height.html + background-size/vector/tall--cover--nonpercent-width-percent-height-viewbox.html + background-size/vector/tall--cover--nonpercent-width-percent-height.html + background-size/vector/tall--cover--omitted-width-nonpercent-height-viewbox.html + background-size/vector/tall--cover--omitted-width-nonpercent-height.html + background-size/vector/tall--cover--omitted-width-omitted-height-viewbox.html + background-size/vector/tall--cover--omitted-width-omitted-height.html + background-size/vector/tall--cover--omitted-width-percent-height-viewbox.html + background-size/vector/tall--cover--omitted-width-percent-height.html + background-size/vector/tall--cover--percent-width-nonpercent-height-viewbox.html + background-size/vector/tall--cover--percent-width-nonpercent-height.html + background-size/vector/tall--cover--percent-width-omitted-height-viewbox.html + background-size/vector/tall--cover--percent-width-omitted-height.html + background-size/vector/tall--cover--percent-width-percent-height-viewbox.html + background-size/vector/tall--cover--percent-width-percent-height.html + background-size/vector/tall--cover--width.html + background-size/vector/wide--12px-auto--nonpercent-width-nonpercent-height-viewbox.html + background-size/vector/wide--12px-auto--nonpercent-width-nonpercent-height.html + background-size/vector/wide--12px-auto--nonpercent-width-omitted-height-viewbox.html + background-size/vector/wide--12px-auto--nonpercent-width-omitted-height.html + background-size/vector/wide--12px-auto--nonpercent-width-percent-height-viewbox.html + background-size/vector/wide--12px-auto--nonpercent-width-percent-height.html + background-size/vector/wide--12px-auto--omitted-width-nonpercent-height-viewbox.html + background-size/vector/wide--12px-auto--omitted-width-nonpercent-height.html + background-size/vector/wide--12px-auto--omitted-width-omitted-height-viewbox.html + background-size/vector/wide--12px-auto--omitted-width-omitted-height.html + background-size/vector/wide--12px-auto--omitted-width-percent-height-viewbox.html + background-size/vector/wide--12px-auto--omitted-width-percent-height.html + background-size/vector/wide--12px-auto--percent-width-nonpercent-height-viewbox.html + background-size/vector/wide--12px-auto--percent-width-nonpercent-height.html + background-size/vector/wide--12px-auto--percent-width-omitted-height-viewbox.html + background-size/vector/wide--12px-auto--percent-width-omitted-height.html + background-size/vector/wide--12px-auto--percent-width-percent-height-viewbox.html + background-size/vector/wide--12px-auto--percent-width-percent-height.html + background-size/vector/wide--auto--nonpercent-width-nonpercent-height-viewbox.html + background-size/vector/wide--auto--nonpercent-width-nonpercent-height.html + background-size/vector/wide--auto--nonpercent-width-omitted-height-viewbox.html + background-size/vector/wide--auto--nonpercent-width-omitted-height.html + background-size/vector/wide--auto--nonpercent-width-percent-height-viewbox.html + background-size/vector/wide--auto--nonpercent-width-percent-height.html + background-size/vector/wide--auto--omitted-width-nonpercent-height-viewbox.html + background-size/vector/wide--auto--omitted-width-nonpercent-height.html + background-size/vector/wide--auto--omitted-width-omitted-height-viewbox.html + background-size/vector/wide--auto--omitted-width-omitted-height.html + background-size/vector/wide--auto--omitted-width-percent-height-viewbox.html + background-size/vector/wide--auto--omitted-width-percent-height.html + background-size/vector/wide--auto--percent-width-nonpercent-height-viewbox.html + background-size/vector/wide--auto--percent-width-nonpercent-height.html + background-size/vector/wide--auto--percent-width-omitted-height-viewbox.html + background-size/vector/wide--auto--percent-width-omitted-height.html + background-size/vector/wide--auto--percent-width-percent-height-viewbox.html + background-size/vector/wide--auto--percent-width-percent-height.html + background-size/vector/wide--auto-32px--nonpercent-width-nonpercent-height-viewbox.html + background-size/vector/wide--auto-32px--nonpercent-width-nonpercent-height.html + background-size/vector/wide--auto-32px--nonpercent-width-omitted-height-viewbox.html + background-size/vector/wide--auto-32px--nonpercent-width-omitted-height.html + background-size/vector/wide--auto-32px--nonpercent-width-percent-height-viewbox.html + background-size/vector/wide--auto-32px--nonpercent-width-percent-height.html + background-size/vector/wide--auto-32px--omitted-width-nonpercent-height-viewbox.html + background-size/vector/wide--auto-32px--omitted-width-nonpercent-height.html + background-size/vector/wide--auto-32px--omitted-width-omitted-height-viewbox.html + background-size/vector/wide--auto-32px--omitted-width-omitted-height.html + background-size/vector/wide--auto-32px--omitted-width-percent-height-viewbox.html + background-size/vector/wide--auto-32px--omitted-width-percent-height.html + background-size/vector/wide--auto-32px--percent-width-nonpercent-height-viewbox.html + background-size/vector/wide--auto-32px--percent-width-nonpercent-height.html + background-size/vector/wide--auto-32px--percent-width-omitted-height-viewbox.html + background-size/vector/wide--auto-32px--percent-width-omitted-height.html + background-size/vector/wide--auto-32px--percent-width-percent-height-viewbox.html + background-size/vector/wide--auto-32px--percent-width-percent-height.html + background-size/vector/wide--contain--height.html + background-size/vector/wide--contain--nonpercent-width-nonpercent-height-viewbox.html + background-size/vector/wide--contain--nonpercent-width-nonpercent-height.html + background-size/vector/wide--contain--nonpercent-width-omitted-height-viewbox.html + background-size/vector/wide--contain--nonpercent-width-omitted-height.html + background-size/vector/wide--contain--nonpercent-width-percent-height-viewbox.html + background-size/vector/wide--contain--nonpercent-width-percent-height.html + background-size/vector/wide--contain--omitted-width-nonpercent-height-viewbox.html + background-size/vector/wide--contain--omitted-width-nonpercent-height.html + background-size/vector/wide--contain--omitted-width-omitted-height-viewbox.html + background-size/vector/wide--contain--omitted-width-omitted-height.html + background-size/vector/wide--contain--omitted-width-percent-height-viewbox.html + background-size/vector/wide--contain--omitted-width-percent-height.html + background-size/vector/wide--contain--percent-width-nonpercent-height-viewbox.html + background-size/vector/wide--contain--percent-width-nonpercent-height.html + background-size/vector/wide--contain--percent-width-omitted-height-viewbox.html + background-size/vector/wide--contain--percent-width-omitted-height.html + background-size/vector/wide--contain--percent-width-percent-height-viewbox.html + background-size/vector/wide--contain--percent-width-percent-height.html + background-size/vector/wide--contain--width.html + background-size/vector/wide--cover--height.html + background-size/vector/wide--cover--nonpercent-width-nonpercent-height-viewbox.html + background-size/vector/wide--cover--nonpercent-width-nonpercent-height.html + background-size/vector/wide--cover--nonpercent-width-omitted-height-viewbox.html + background-size/vector/wide--cover--nonpercent-width-omitted-height.html + background-size/vector/wide--cover--nonpercent-width-percent-height-viewbox.html + background-size/vector/wide--cover--nonpercent-width-percent-height.html + background-size/vector/wide--cover--omitted-width-nonpercent-height-viewbox.html + background-size/vector/wide--cover--omitted-width-nonpercent-height.html + background-size/vector/wide--cover--omitted-width-omitted-height-viewbox.html + background-size/vector/wide--cover--omitted-width-omitted-height.html + background-size/vector/wide--cover--omitted-width-percent-height-viewbox.html + background-size/vector/wide--cover--omitted-width-percent-height.html + background-size/vector/wide--cover--percent-width-nonpercent-height-viewbox.html + background-size/vector/wide--cover--percent-width-nonpercent-height.html + background-size/vector/wide--cover--percent-width-omitted-height-viewbox.html + background-size/vector/wide--cover--percent-width-omitted-height.html + background-size/vector/wide--cover--percent-width-percent-height-viewbox.html + background-size/vector/wide--cover--percent-width-percent-height.html + background-size/vector/wide--cover--width.html + background-size/vector/zero-height-ratio-5px-auto.html + background-size/vector/zero-height-ratio-auto-5px.html + background-size/vector/zero-height-ratio-auto-auto.html + background-size/vector/zero-height-ratio-contain.html + background-size/vector/zero-height-ratio-cover.html + background-size/vector/zero-ratio-no-dimensions-5px-auto.html + background-size/vector/zero-ratio-no-dimensions-auto-5px.html + background-size/vector/zero-ratio-no-dimensions-auto-auto.html + background-size/vector/zero-ratio-no-dimensions-contain.html + background-size/vector/zero-ratio-no-dimensions-cover.html + background-size/vector/zero-width-ratio-5px-auto.html + background-size/vector/zero-width-ratio-auto-5px.html + background-size/vector/zero-width-ratio-auto-auto.html + background-size/vector/zero-width-ratio-contain.html + background-size/vector/zero-width-ratio-cover.html + css3-background-size-001.html + css3-background-size-contain.html + css3-background-size.html + inheritance.sub.html + subpixel-repeat-no-repeat-mix.html + parsing/background-size-computed.html + parsing/background-size-invalid.html + parsing/background-size-valid.html + + + This property specifies the size of each [=background image=]. + The property's value is given as a comma-separated list + of <> values where + +
<> = [ <> | auto ]{1,2} | cover | contain
+ + Values have the following meanings: + +
+
contain
+
+ Scale the image, while preserving its [=natural aspect ratio=] (if any), + to the largest size such that both its width and its height + can fit inside the [=background positioning area=]. + +
cover
+
+ Scale the image, while preserving its [=natural aspect ratio=] (if any), + to the smallest size such that both its width and its height + can completely cover the [=background positioning area=]. + +
[ <> + | auto ]{1,2}
+
+ The first value gives the width of the corresponding image, + the second value its height. + If only one value is given + the second is assumed to be ''background-size/auto''. + + A <> is relative to the [=background positioning area=]. + + An ''background-size/auto'' value for one dimension + is resolved by using the image's [=natural aspect ratio=] + and the size of the other dimension, + or failing that, using the image's [=natural size=], + or failing that, treating it as ''100%''. + + If both values are ''background-size/auto'' + then the [=natural width=] and/or [=natural height|height=] of the image + should be used, if any, + the missing dimension (if any) behaving as ''background-size/auto'' + as described above. + If the image has neither [=natural size=], + its size is determined as for ''contain''. + + Negative values are invalid. +
+ +
+ Here are some examples. + The first example stretches the background image + independently in both dimensions + to completely cover the content area: + +
+		div {
+			background-image: url(plasma.png);
+			background-repeat: no-repeat;
+			background-size: 100% 100%;
+			background-origin: content-box;
+		}
+		
+ + 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-box;
+		}
+		
+ + This example forces the background image to be 15 by 15 pixels: + +
+		p {
+			background-size: 15px 15px;
+			background-image: url(tile.png);
+		}
+		
+ + This example uses the image's natural size. + Note that this is the only possible behavior in CSS level 1 and 2. + +
+		body {
+			background-size: auto;            /* default */
+			background-image: url(flower.png);
+		}
+		
+ + The following example rounds the height of the image to 33.3%, + up from the specified value of 30%. + At 30%, three images would fit entirely and a fourth only partially. + After rounding, three images fit exactly. + The width of the image is 20% of the background positioning area width + and is not rounded. + +
+		p {
+			background-image: url(chain.png);
+			background-repeat: no-repeat round;
+			background-size: 20% 30%;
+		}
+		
+
+ + If 'background-repeat' is ''background-repeat/round'' + for one (or both) dimensions, + there is a second step. + The UA must scale the image in that dimension (or both dimensions) + so that it fits a whole number of times in the [=background positioning area=]. + In the case of the width (height is analogous): + +
+ If X ≠ 0 is the width of the image after step one + and W is the width of the background positioning area, + then the rounded width + X' = W / round(W / X) + where round() is a function that returns the nearest natural number + (integer greater than zero). +
+ + If 'background-repeat' is ''background-repeat/round'' for one dimension only + and if 'background-size' is ''background-size/auto'' for the other dimension, + then there is a third step: + that other dimension is scaled so that the original aspect ratio is restored. + +
+ In this example the background image is shown at its natural size: + +
+		div {
+			background-image: url(image1.png);
+			background-repeat: repeat;         /* default */
+			background-size: auto;             /* default */
+		}
+		
+ + In the following example, the background is shown with a width of + 3em and its height is scaled proportionally to keep the original + aspect ratio: + +
+		div {
+			background-image: url(image2.png);
+			background-repeat: repeat;         /* default */
+			background-size: 3em;              /* = '3em auto' */
+		}
+		
+ + In the following example, + the background is shown with a width of approximately 3em: + scaled so that it fits a whole number of times in the width of the background. + The height is scaled proportionally to keep the original aspect ratio: + +
+		div {
+			background-image: url(image3.png);
+			background-repeat: round repeat;
+			background-size: 3em auto;
+		}
+		
+ + In the following example, the background image is shown + with a width of 3em and a height that is either + the height corresponding to that width at the original aspect ratio + or slightly less: + +
+		div {
+			background-image: url(image4.png);
+			background-repeat: repeat round;
+			background-size: 3em auto;
+		}
+		
+ + In the following example, + the background image is shown with a height of approximately 4em: + scaled slightly so that it fits a whole number of times in the background height. + The width is the approximately the width that corresponds to + a 4em height at the original aspect ratio: + scaled slightly so that it fits a whole number of times + in the background width. + +
+		div {
+			background-image: url(image5.png);
+			background-repeat: round;
+			background-size: auto 4em;
+		}
+		
+
+ + If the background image's width or height resolves to zero, + this causes the image not to be displayed. + (The effect is the same as if it had been a transparent image.) + + See [[#layering]] for how 'background-size' interacts + with other comma-separated background properties + to form each [=background image layer=]. +

Background Image Layers: the 'background-tbd' shorthand property

@@ -413,6 +1689,321 @@ Background Image Layers: the 'background-tbd' shorthand property
+

+Backgrounds Shorthand: the 'background' property

+ +
+	Name: background
+	Value: <>#? , <>
+	Applies to: all elements
+	Inherited: no
+	
+ + + background-331.html + background-332.html + background-333.html + background-334.html + background-335.html + background-336.html + parsing/background-computed.html + parsing/background-invalid.html + parsing/background-shorthand-serialization.html + parsing/background-valid.html + + + The 'background' property is a [=shorthand property=] + for setting most background properties at the same place in the style sheet. + The number of comma-separated items defines the number of [=background image layers=]. + Given a valid declaration, for each layer + the shorthand first sets the corresponding value of each of + 'background-image', + 'background-position', + 'background-size', + 'background-repeat', + 'background-origin', + 'background-clip' + and 'background-attachment' to + that property's [=initial value=], + then assigns any explicit values + specified for this layer in the declaration. + Finally 'background-color' is set to the specified color, if any, + else set to its initial value. + + This property's value is given as a comma-separated list + of values where + +
+	<bg-layer> = <> || <> [ / <> ]? || <> || <> || <> || <>
+	<final-bg-layer> =  <> || <> [ / <> ]? || <> || <> || <> || <> || <<'background-color'>>
+ + Note: A color is permitted in <>, but not in <>. + + If one <> value is present + then it sets both 'background-origin' and 'background-clip' to that value. + If two values are present, + then the first sets 'background-origin' and the second 'background-clip'. + +
+ 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 values. In the + second rule, many individual properties have been specified. + +
+		body { background: red }
+		p { background: url("chess.png") 40% / 10em gray
+		                round fixed border-box; }
+		
+ + The first rule is equivalent to: + +
+		body {
+		    background-color: red;
+		    background-position: 0% 0%;
+		    background-size: auto;
+		    background-repeat: repeat;
+		    background-clip: border-box;
+		    background-origin: padding-box;
+		    background-attachment: scroll;
+		    background-image: none }
+		
+ + The second is equivalent to: + +
+		p {
+			background-color: gray;
+			background-position: 40% 50%;
+			background-size: 10em auto;
+			background-repeat: round;
+			background-clip: border-box;
+			background-origin: border-box;
+			background-attachment: fixed;
+			background-image: url(chess.png);
+		}
+		
+
+ +
+ The following example shows how a both + a background color (''#CCC'') and a background image (''url(metal.jpg)'') + are set. + The image is rescaled to the full width of the element: + +
+		E { background: #CCC url("metal.jpg") top left / 100% auto no-repeat}
+		
+
+ +
+ Another example shows equivalence: + +
+		div {
+			background: padding-box url(paper.jpg) white center;
+		}
+
+		div {
+			background-color: white;
+			background-image: url(paper.jpg);
+			background-repeat: repeat;
+			background-attachment: scroll;
+			background-position: center;
+			background-clip: padding-box;
+			background-origin: padding-box;
+			background-size: auto auto;
+		}
+		
+
+ +
+ The following declaration with multiple, comma-separated values + +
+		background: url(a.png) top left no-repeat,
+		            url(b.png) center / 100% 100% no-repeat,
+		            url(c.png) white;
+		
+ + is equivalent to + +
+		background-image:      url(a.png),  url(b.png),          url(c.png);
+		background-position:   top left,    center,              top left;
+		background-repeat:     no-repeat,   no-repeat,           repeat;
+		background-clip:       border-box,  border-box,          border-box;
+		background-origin:     padding-box, padding-box,         padding-box;
+		background-size:       auto auto,   100% 100%,           auto auto;
+		background-attachment: scroll,      scroll,              scroll;
+		background-color:      white;
+		
+
+ +

+Layering Multiple Background Images

+ + The background of a box can have multiple + background image layers. + The number of layers is determined by + the number of comma-separated values in the 'background-image' property. + Note that a value of ''background-image/none'' still creates a layer. + + + background-none-none-and-color.html + order-of-images.htm + scroll-positioned-multiple-background-images.html + + + Each of the [=background images=] is sized, positioned, and tiled + according to the corresponding value in the other background properties. + The lists are matched up from the first value: + excess values at the end are not used. + If a property doesn't have enough comma-separated values + to match the number of layers, + the [=UA=] must calculate its [=used value=] + by repeating the list of values until there are enough. + +
+ For example, this set of declarations: + +
+		background-image: url(flower.png), url(ball.png), url(grass.png);
+		background-position: center center, 20% 80%, top left, bottom right;
+		background-origin: border-box, content-box;
+		background-repeat: no-repeat;
+		
+ + has exactly the same effect as this set, + with the extra position dropped + and the missing values for 'background-origin' and 'background-repeat' + filled in (emphasized for clarity): + +
+		background-image: url(flower.png), url(ball.png), url(grass.png);
+		background-position: center center, 20% 80%, top left;
+		background-origin: border-box, content-box, border-box;
+		background-repeat: no-repeat, no-repeat, no-repeat;
+		
+
+ + The first image in the list is the [=layer=] closest to the user, + the next one is painted behind the first, and so on. + The background color, if present, + is painted below all of the other [=layers=]. + + Note: The [[css-borders-4#border-images|border-image properties]] + can also define a background image, + which, if present, is painted on top of + the background [=layers=] created by the background properties. + +

+Backgrounds of Special Elements

+ + The document canvas + is the infinite surface over which the document is rendered. [[!CSS2]] + Since no element corresponds to the canvas, + in order to allow styling of the canvas + CSS propagates the background of the [=root element=] + (or, in the case of HTML, the <body> element) + as described below. + However, if the element whose background would be used for the canvas + is ''display: none'', + then the [=canvas background=] is transparent. + + If the [=canvas background=] is not opaque, + the canvas surface below it shows through. + The texture of the [=canvas surface=] is UA-dependent + (but is typically an opaque white). + +

+The Canvas Background and the Root Element

+ + The background of the [=root element=] becomes the canvas background + and its [=background painting area=] extends + to cover the entire canvas. + However, any images are sized and positioned relative to the root element’s box + as if they were painted for that element alone. + (In other words, the + background positioning area + is determined as for the root element.) + The root element does not paint this background again, + i.e., the [=used value=] of its background is ''transparent''. + + + background-margin-iframe-root.html + background-margin-root.html + background-margin-transformed-root.html + background-margin-will-change-root.html + + +

+The Canvas Background and the HTML <body> Element

+ + For documents whose root element is + an HTML HTML element + or an XHTML html element [[!HTML]]: + if the [=computed value=] of 'background-image' on the [=root element=] + is ''background-image/none'' and its 'background-color' is ''transparent'', + user agents must instead propagate + the [=computed values=] of the background properties + from that element's first + HTML BODY or XHTML body + child element. + The [=used values=] + of that BODY element's background properties + are their [=initial values=], + and the propagated values are treated + as if they were specified on the root element. + It is recommended that authors of HTML documents specify the canvas background + using the BODY element + rather than the HTML element. + + + document-canvas-remove-body.html + + + Note: Using [=containment=] disables + this special handling of the HTML <{body}> element. + See the [[CSS-CONTAIN-1#contain-property]] for details. + +
+ According to these rules, the canvas underlying the following HTML document + will have a “marble” background: + +
+		<!DOCTYPE html PUBLIC '-//W3C//DTD HTML 4.0//EN'
+		  >
+		<html>
+		  <head>
+		    <title>Setting the canvas background</title>
+		    <style type="text/css">
+		       body { background: url("http://example.org/marble.png") }
+		    </style>
+		  </head>
+		  <body>
+		    <p>My background is marble.</p>
+		  </body>
+		</html>
+		
+
+ +

+The ''::first-line'' Pseudo-element‘s Background

+ + The ''::first-line'' pseudo-element + is like an inline-level element + for the purposes of the background + (see section 5.12.1 of [[!CSS2]]). + That means, e.g., that in a left-justified first line, + the background does not necessarily extend + all the way to the right edge. + + + linear-gradient-currentcolor-first-line.html + +

Changes

@@ -428,7 +2019,7 @@ Additions since [[CSS3BG]]

Acknowledgments

-

In addition to the many contributors to the [[CSS1]], [[CSS21]], +

In addition to the many contributors to the [[CSS1]], [[CSS2]], and [[CSS3BG]] predecessors to this module, the editors would like to thank Tab Atkins, @@ -442,3 +2033,368 @@ No new privacy considerations have been reported on this specification.

Security Considerations

No new security considerations have been reported on this specification. + + + + + + + + \ No newline at end of file