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.)
+
+
+
+
+
+ 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
+
+
+ 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
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
- }
-
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 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.
+
+
+ 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
+
+ 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:
+
+
+
+ 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.
+
+
+
+ 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:
+
+
+
+ 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:
+
+
+
+ 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:
+
+
+
+ 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:
+
+
+
+ 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
+ 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
+
+
+
+ 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 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}
+
+ 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.