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.
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.
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
These properties specify whether and how background images are tiled
along one axis after they have been
sized and positioned.
repeat
The image is repeated in the given direction as often as needed
to cover the [=background painting area=].
space
The image is repeated in the given direction as often as will fit
within the [=background positioning area=] without being
clipped and then the repeated images are spaced out to fill the area.
The first and last images touch the edges of the area.
If the [=background painting area=] is larger than the background positioning area,
then the pattern repeats to fill the background painting area.
The value of 'background-position' for this direction is ignored,
unless there is not enough space for two copies of the image in this direction,
in which case only one image is placed and
'background-position' determines its position in this direction.
round
The image is repeated in the given direction as often as will fit
within the [=background positioning area=].
If it doesn't fit a whole number of times,
it is rescaled so that it does.
See the formula under 'background-size'.
If the [=background painting area=] is larger than the background positioning area,
then the pattern repeats to fill the background painting area.
no-repeat
The image is placed once and not repeated in the given direction.
Unless one of the axes is set to ''no-repeat'',
the whole background painting area will be tiled,
i.e., not just one vertical strip and one horizontal strip.
Example(s):
body {
background: white url("pendant.png");
background-repeat-y: repeat;
background-position: center;
}
The effect of ''repeat-y'':
One copy of the background image is centered,
and other copies are put above and below it
to make a vertical band behind the element.
See the section [[#layering]] for how
'background-repeat-x',
'background-repeat-y',
'background-repeat-block',
and 'background-repeat-inline'
interact with other comma-separated background properties
to form each background image layer.
Tiling Images Shorthand: the 'background-repeat' property
Name: background-repeat
Value: <>#
Initial: repeat
Applies to: all elements
Inherited: no
Percentages: N/A
Computed value: list, each item a pair of keywords, one per dimension
Animation type: discrete
Computes to ''repeat'' in the [=block axis=] and ''no-repeat'' in the [=inline axis=].
repeat-inline
Computes to ''repeat'' in the [=inline axis=] and ''no-repeat'' in the [=block axis=].
''background-repeat-x/repeat''
Computes to ''repeat repeat''.
''background-repeat-x/space''
Computes to ''space space''
''background-repeat-x/round''
Computes to ''round round''
''background-repeat-x/no-repeat''
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.
Example(s):
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.
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?
Affixing Images: the 'background-attachment' property
Name: background-attachment
Value: <>#
Initial: scroll
Applies to: all elements
Inherited: no
Percentages: N/A
Computed value: list, each item the keyword as specified
Animation type: discrete
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.)
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.
This example creates an infinite vertical band
that remains “glued” to the viewport when the document is scrolled.
body {
background: red url("pendant.gif");
background-repeat: repeat-y;
background-attachment: fixed;
}
Note: User agents that do not support ''fixed'' backgrounds
(for example due to limitations of the hardware platform)
will ignore declarations
with the keyword ''fixed''.
For example:
body {
/* For all UAs: */
background: white url(paper.png) scroll;
/* For UAs that do fixed backgrounds: */
background: white url(ledger.png) fixed;
}
h1 {
/* For all UAs: */
background: silver;
/* For UAs that do fixed backgrounds: */
background: url(stripe.png) fixed, white url(ledger.png) fixed;
}
See [[#layering]] for how 'background-attachment' interacts
with other comma-separated background properties
to form each [=background image layer=].
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.
Name: background-position-x
Value: [ center | [ [ left | right | x-start | x-end ]? <>? ]! ]#
Initial: 0%
Inherited: no
Logical property group: background-position
Percentages: refer to width of background positioning area minus width of background image
Computed value: A list, each item consisting of: an offset given as a computed <> value, plus an origin keyword
Animation type: repeatable list
This property specifies the background position's horizontal component.
An omitted origin keyword is assumed to be ''background-position-x/left''.
Name: background-position-y
Value: [ center | [ [ top | bottom | y-start | y-end ]? <>? ]! ]#
Initial: 0%
Inherited: no
Logical property group: background-position
Percentages: refer to height of background positioning area minus height of background image
Computed value: A list, each item consisting of: an offset given as a computed <> value, plus an origin keyword
Animation type: repeatable list
This property specifies the background position's vertical component.
An omitted origin keyword is assumed to be ''background-position-y/top''.
Name: background-position-inline
Value: [ center | [ [ start | end ]? <>? ]! ]#
Initial: 0%
Inherited: no
Logical property group: background-position
Percentages: refer to inline-size of background positioning area minus inline-size of background image
Computed value: A list, each item consisting of: an offset given as a computed <> value, plus an origin keyword
Animation type: repeatable list
This property specifies the background position's inline-axis component.
An omitted origin keyword is assumed to be ''background-position-inline/start''.
Name: background-position-block
Value: [ center | [ [ start | end ]? <>? ]! ]#
Initial: 0%
Inherited: no
Logical property group: background-position
Percentages: refer to size of background positioning area minus size of background image
Computed value: A list, each item consisting of: an offset given as a computed <> value, plus an origin keyword
Animation type: repeatable list
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 areaminus 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-composition.html
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
Name: background-clip
Value: <>#
Initial: border-box
Inherited: no
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-out-of-flow-child.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
<bg-clip> = <> | [ border-area || text ]
Issue: Or should this be defining the -webkit-background-clip property,
saying that all the values are identical,
with this additional ''text'' value?
<>
The background is painted within (clipped to)
the specified box of the element.
text
The background is painted within (clipped to)
the intersection of the border box
and the geometry of the text including any decorations and emphasis marks in the element and its [=in-flow=] and floated descendants.
The text color has no effect on the painting of the background.
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'.
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 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.
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 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=].
Serialization of 'background-size' values
The [=specified value=] and [=computed value=] of the <> type
always serialize as two values, even when the second value is ''background-size/auto'',
due to the [[cssom#serializing-css-values|shortest, most backwards-compatible serialization principle]].
Background Image Layers: the 'background-tbd' shorthand property
Not Ready For Implementation
This section is not yet ready for implementation.
It exists in this repository to record the ideas and promote discussion.
Before attempting to implement anything of this section,
please contact the CSSWG at www-style@w3.org.
Name: background-tbd
Value: <>#
Initial: see individual properties
Applies to: all elements
Inherited: no
Percentages: see individual properties
Computed value: see individual properties
Animation type: see individual properties
The 'background-tbd' property is a [=shorthand property=]
that sets all the same properties as the 'background' shorthand
except for 'background-color',
allowing authors to easily declare and position background images
while letting 'background-color' cascade through independently.
Issue:
The name of this property is discussed in
issue 9083.
This example sets two background layers later in the cascade.
By using 'background-tbd', the previously set 'background-color'
won't be overridden.
p {
background-color: green;
}
p {
background-tbd:
url(a.png) top left,
url(b.png) top left no-repeat;
}
This example tries to set the background color in addition to
the background image. But for that to work,
'background' needs to be used instead of 'background-tbd'.
So the 'background-tbd' declaration will be dropped.
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.
However, if a value is set that is only valid in 'background-clip',
then it sets 'background-clip' to that value and 'background-origin' to ''background-origin/border-box''.
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}
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
Additions since [[CSS3BG]]
* turned 'background-position' into a shorthand and added physical and logical longhands
* added logical keywords to <>
* added ''background-clip/border-area'' and ''background-clip/text'' values to 'background-clip'
* added 'background-tbd'
* added 'background-repeat-*' longhands
* added logical keywords ''background-repeat/repeat-block'' and ''background-repeat/repeat-inline'' to 'background-repeat'
Acknowledgments
In addition to the many contributors to the [[CSS1]], [[CSS2]],
and [[CSS3BG]] predecessors to this module,
the editors would like to thank
Tab Atkins,
and Håkon Wium Lie
for their suggestions and feedback specifically for this Level 4.
Privacy Considerations
No new privacy considerations have been reported on this specification.