<pre class='metadata'>

Title: CSS Backgrounds and Borders Module Level 3

Status: ED

Implementation Report: https://wpt.fyi/results/css/css-backgrounds

Work Status: Testing

Shortname: css-backgrounds

Level: 3

Group: csswg

ED: https://drafts.csswg.org/css-backgrounds/

TR: https://www.w3.org/TR/css-backgrounds-3/

Previous Version: https://www.w3.org/TR/2020/CR-css-backgrounds-3-20201222/

Previous Version: https://www.w3.org/TR/2017/CR-css-backgrounds-3-20171017/

Previous version: https://www.w3.org/TR/2014/CR-css3-background-20140909/

Former Editor: Bert Bos, W3C, [email protected], w3cid 3343

Editor: Elika J. Etemad / fantasai, Apple, http://fantasai.inkedblade.net/contact, w3cid 35400

Editor: Brad Kemper, Invited Expert, [email protected], w3cid 43245

Abstract: This draft contains the features of CSS relating to borders and backgrounds. The main extensions compared to <a href="https://www.w3.org/TR/CSS2/">level&nbsp;2</a> are borders consisting of images, boxes with multiple backgrounds, boxes with rounded corners and boxes with shadows.

WPT Path Prefix: css/css-backgrounds/

WPT Display: closed

At risk: animatability of 'box-shadow'

At risk: applicability of 'border' and its longhands to [=ruby base containers=] and [=ruby annotation containers=]

Ignored Vars: width of background positioning area, width of background image, height of background positioning area, height of background image, X, X', Li, Ltop, Lbottom, Lleft, Lright, Wside, Wleft, Wright, Wtop, Wbottom, spread distance

</pre>

<pre class="link-defaults">

spec:css2; type:type; text:<uri>

spec:css2; type:property; text:display

spec:css2; type:value; text:table

spec:css2; type:value; text:inline-table

spec:css2; type:value; text:table-cell

spec:css2; type:property; text:overflow

spec:css2; type:value; text:visible

spec:css2; type:dfn; text:viewport

spec:css-break-4; type:dfn; text:fragment

spec:css-color-4; type:property; text:color

spec:css-color-4; type:value; text:transparent

spec:selectors-3; type:selector; text: ::first-letter

spec:selectors-3; type:selector; text: ::first-line

spec:css-values-3; type:type; text:<position>

</pre>

<h2 id="introduction">Introduction</h2>

<em>This subsection is not normative.</em>

When elements are rendered according to the

<a href="https://www.w3.org/TR/css-box-3/#box-model">CSS box model</a> [[!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.)

<figure>

<img src="images/box.png"

alt="Diagram of a typical box, showing the content, padding, border and margin areas"

>

<figcaption>

The various areas and edges of a typical box.

(This diagram is explained in the CSS Box Model Module [[!CSS-BOX-3]].)

</figcaption>

</figure>

The properties of this module deal with the decoration of the [=border area=]

and with the background of the [=content area|content=], [=padding area|padding=], and [=border area|border=] areas.

Additionally the box may be given a “drop-shadow” effect

with the 'box-shadow' property.

If an element is broken into multiple [=box fragments=],

'box-decoration-break' [[CSS-BREAK-3]] 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]].

<h3 id="placement">

Module Interactions</h3>

This module replaces and extends the background and border features

defined in [[!CSS2]] sections 8.5 and 14.2.

All properties in this module apply to the ''::first-letter'' [=pseudo-element=].

The <a href="#backgrounds">background properties</a>

and <a href="#corners">border-radius properties</a> also apply

to the ''::first-line'' [=pseudo-element=].

The UA may (but is not required to)

apply the 'border-image' or 'box-shadow' properties to ''::first-line''.

The UA must not

apply the <a href="#borders">border-color/style/width properties</a>

to ''::first-line''.

[[!CSS2]]

<h3 id="values">

Value Definitions</h3>

This specification follows the <a href="https://www.w3.org/TR/CSS2/about.html#property-defs">CSS property definition conventions</a> from [[!CSS2]]

using the <a href="https://www.w3.org/TR/css-values-3/#value-defs">value definition syntax</a> from [[!CSS-VALUES-3]].

Value types not defined in this specification are defined in CSS Values &amp; Units [[!CSS-VALUES-3]].

Combination with other CSS modules may expand the definitions of these value types.

For example, combining with <a href="https://www.w3.org/TR/css-images/">CSS Images</a>

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 <a>CSS-wide keywords</a> as their property value.

For readability they have not been repeated explicitly.

<h2 id="backgrounds">

Backgrounds</h2>

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

<h3 id="layering">

Layering Multiple Background Images</h3>

The background of a box can have multiple

<dfn export lt="background image layer" local-lt="layer">background image layers</dfn>.

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.

<wpt>

background-none-none-and-color.html

order-of-images.htm

scroll-positioned-multiple-background-images.html

</wpt>

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.

<div class="example">

For example, this set of declarations:

<pre>

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;

</pre>

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):

<pre>

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<strong>, border-box</strong>;

background-repeat: no-repeat<strong>, no-repeat, no-repeat</strong>;

</pre>

</div>

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 <a href="#border-images">border-image properties</a>

can also define a background image,

which, if present, is painted on top of

the background [=layers=] created by the background properties.

<h3 id="background-color" oldids="the-background-color">

Base Color: the 'background-color' property</h3>

<pre class="propdef">

Name: background-color

Value: <<color>>

Initial: transparent

Applies to: all elements

Inherited: no

Percentages: N/A

Computed value: computed color

Animation type: by computed value

</pre>

<wpt>

animations/background-color-animation-backdrop-infinite-duration-crash.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

</wpt>

This property sets the <dfn export id="background-color-layer">background color</dfn> of a box.

This color is drawn behind any background images.

<div class="example">

Example:

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

</div>

The [=background color=] is clipped

according to the 'background-clip' value

associated with the bottom-most [=background image layer=].

<h3 id="background-image" oldids="the-background-image">

Image Sources: the 'background-image' property</h3>

<pre class="propdef">

Name: background-image

Value: <<bg-image>>#

Initial: none

Applies to: all elements

Inherited: no

Percentages: N/A

Computed value: list, each item either an <<image>> or the keyword ''background-image/none''

Animation type: discrete

</pre>

<wpt>

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

</wpt>

This property specifies the <dfn export lt="background image" local-lt="image" id="background-images">background image(s)</dfn> of an element.

Images are drawn with the first specified one on top (closest to the user)

and each subsequent image behind the previous one.

The property's value is given as a comma-separated list

of <<bg-image>> values where

<pre class=prod><dfn><<bg-image>></dfn> = <<image>> | none</pre>

A value of <dfn value for="background-image">none</dfn>

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 <a href="https://www.w3.org/TR/2008/NOTE-WCAG20-TECHS-20081211/F3">Web Content Accessibility Guideline F3</a> [[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 &lt;img&gt; tag in HTML.

Note: <a href="https://www.w3.org/TR/media-frags/#naming-space">Media fragments</a>

can be used to display a portion of an image.

The <a href="https://www.w3.org/TR/css-images/">CSS Images</a> module

will provide fallback syntax for image formats

and include additional controls for image display.

<div class="example">

Some examples specifying background images:

<pre>

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); }

</pre>

</div>

Implementations may optimize

by not downloading and drawing images that are not visible

(e.g., because they are behind other, fully opaque images).

<h3 id="background-repeat" oldids="the-background-repeat">

Tiling Images: the 'background-repeat' property</h3>

<pre class="propdef">

Name: background-repeat

Value: <<repeat-style>>#

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

</pre>

<wpt>

animations/discrete-no-interpolation.html

background-repeat-round-1a.html

background-repeat-round-1b.html

background-repeat-round-1c.html

background-repeat-round-1d.html

background-repeat-round-1e.html

background-repeat-round-2.html

background-repeat-round-3.html

background-repeat-round-4.html

background-repeat-space-10.html

background-repeat-space-1a.html

background-repeat-space-1b.html

background-repeat-space-1c.html

background-repeat-space-2.html

background-repeat-space-3.html

background-repeat-space-4.html

background-repeat-space-5.html

background-repeat-space-6.html

background-repeat-space-7.html

background-repeat-space-8.html

background-repeat-space-9.html

background-repeat/background-repeat-no-repeat.xht

background-repeat/background-repeat-repeat-x.xht

background-repeat/background-repeat-repeat-y.xht

background-repeat/background-repeat-round-roundup.xht

background-repeat/background-repeat-round.xht

background-repeat/background-repeat-space.xht

background-repeat/gradient-repeat-spaced-with-borders.html

inheritance.sub.html

parsing/background-repeat-computed.html

parsing/background-repeat-invalid.html

parsing/background-repeat-valid.html

subpixel-repeat-no-repeat-mix.html

</wpt>

This property specifies how [=background images=] are tiled

after they have been [[#background-size|sized]]

and [[#background-position|positioned]].

The property's value is given as a comma-separated list

of <<repeat-style>> values where

<pre class=prod><dfn><<repeat-style>></dfn> = repeat-x | repeat-y | [repeat | space | round | no-repeat]{1,2}</pre>

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

<dl dfn-type=value dfn-for=background-repeat>

<dt><dfn>repeat-x</dfn>

<dd>

Computes to ''repeat no-repeat''.

<dt><dfn>repeat-y</dfn>

<dd>

Computes to ''no-repeat repeat''.

<dt>''background-repeat/repeat''

<dd>

Computes to ''repeat repeat''.

<dt>''background-repeat/space''

<dd>

Computes to ''space space''

<dt>''background-repeat/round''

<dd>

Computes to ''round round''

<dt>''no-repeat''

<dd>

Computes to ''no-repeat no-repeat''

</dl>

If a <<repeat-style>> value has two keywords,

the first one applies to the horizontal axis,

the second to the vertical one,

as follows:

<dl dfn-for=background-repeat dfn-type=value>

<dt><dfn>repeat</dfn>

<dd>

The [=image=] is repeated in this direction as often as needed

to cover the [=background painting area=].

<dt><dfn>space</dfn>

<dd>

The [=image=] is repeated as often as will fit

within the [=background positioning area=] without being clipped,

and then the 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 axis,

in which case only one image is placed,

and 'background-position' determines its position in this axis.

<dt><dfn>round</dfn>

<dd>

The [=image=] is repeated 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.

<dt><dfn>no-repeat</dfn>

<dd>

The [=image=] is placed once and not repeated in this direction.

</dl>

Unless one of the two keywords is ''no-repeat'',

the whole [=background painting area=] will be tiled,

i.e., not just one vertical strip and one horizontal strip.

<div class="example">

<pre>

body {

background: white url("pendant.png");

background-repeat: repeat-y;

background-position: center;

}

</pre>

<figure>

<img src="images/bg-repeat.png"

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

>

<figcaption>

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.

</figcaption>

</figure>

</div>

<div class=example>

<pre>

body {

background-image: url(dot.png) white;

background-repeat: space

}

</pre>

<figure>

<img src="images/bg-space.png"

alt="Image of an element with a dotted background"

>

<figcaption>

The effect of ''background-repeat/space'':

the image of a dot is tiled to cover the whole background

and the images are equally spaced.

</figcaption>

</figure>

</div>

See [[#layering]] for how 'background-repeat' interacts

with other comma-separated background properties

to form each [=background image layer=].

<h3 id="background-attachment" oldids="the-background-attachment">

Affixing Images: the 'background-attachment' property</h3>

<pre class="propdef">

Name: background-attachment

Value: <<attachment>>#

Initial: scroll

Applies to: all elements

Inherited: no

Percentages: N/A

Computed value: list, each item the keyword as specified

Animation type: discrete

</pre>

<wpt>

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

</wpt>

If [=background images=] are specified,

this property specifies whether they are

fixed with regard to the [=viewport=] (''fixed'')

or scroll along with the box (''scroll'')

or its contents (''local'').

The property's value is given as a comma-separated list

of <<attachment>> keywords where

<pre class=prod><dfn><<attachment>></dfn> = scroll | fixed | local</pre>

<dl dfn-for=background-attachment dfn-type=value>

<dt><dfn>fixed</dfn></dt>

<dd>

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 <a href="https://www.w3.org/TR/CSS2/page.html#page-box">page box</a>

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.

<dt><dfn>local</dfn></dt>

<dd>

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

<dt><dfn>scroll</dfn></dt>

<dd>

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

</dl>

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.

<div class="example">

This example creates an infinite vertical band

that remains “glued” to the viewport when the document is scrolled.

<pre>

body {

background: red url("pendant.gif");

background-repeat: repeat-y;

background-attachment: fixed;

}

</pre>

</div>

Note: User agents that do not support ''fixed'' backgrounds

(for example due to limitations of the hardware platform)

<a href="https://www.w3.org/TR/CSS/#partial">will ignore declarations</a>

with the keyword ''fixed''.

For example:

<pre class=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;

}

</pre>

See [[#layering]] for how 'background-attachment' interacts

with other comma-separated background properties

to form each [=background image layer=].

<h3 id="background-position" oldids="the-background-position">Positioning Images: the 'background-position' property</h3>

<pre class="propdef">

Name: background-position

Value: <<bg-position>>#

Initial: 0% 0%

Applies to: all elements

Inherited: no

Percentages: refer to size of [=background positioning area=]

<em>minus</em> size of background image; see text

Computed value: list,

each item a pair of offsets (horizontal and vertical) from the top left origin

each given as a computed <<length-percentage>> value

Animation type: repeatable list

</pre>

<wpt>

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

</wpt>

If [=background images=] have been specified,

this property specifies their initial position

(after any <a href="#background-size">resizing</a>)

within their corresponding [=background positioning area=].

The property's value is given as a comma-separated list

of <<bg-position>> values where

<pre class=prod>

<dfn><<bg-position>></dfn> = [

[ left | center | right | top | bottom | <<length-percentage>> ]

|

[ left | center | right | <<length-percentage>> ]

[ top | center | bottom | <<length-percentage>> ]

|

[ center | [ left | right ] <<length-percentage>>? ] &amp;&amp;

[ center | [ top | bottom ] <<length-percentage>>? ]

]

</pre>

If only one value is specified,

the second value is assumed to be ''center''.

If two values are given,

a <<length-percentage>> as the first value represents

the horizontal position (or offset)

and a <<length-percentage>> as the second value represents

the vertical position (or offset).

The <<length-percentage>> values here represent

an offset of the top left corner of the background image

from the top left corner of the [=background positioning area=].

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 <<length-percentage>> 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 <em>inward</em>

from the edge of the [=background positioning area=].

Negative values represent an offset <em>outward</em>

from the edge of the [=background positioning area=].

<div class="example">

The following declarations give the stated (horizontal, vertical)

offsets from the top left corner:

<pre>

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 */

</pre>

</div>

<dl dfn-for=background-position dfn-type=value>

<dt><dfn><<percentage>></dfn>

<dd>

A percentage for the horizontal offset is relative to

(<var>width of [=background positioning area=]</var> - <var>width of [=background image=]</var>).

A percentage for the vertical offset is relative to

(<var>height of [=background positioning area=]</var> - <var>height of [=background image=]</var>),

where the size of the image is the size given by 'background-size'.

<div class=example>

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.

<figure>

<img src="images/bg-pos.png"

alt="Diagram of image position within element"

>

<figcaption>

Diagram of the meaning of ''background-position: 75% 50%''.

</figcaption>

</div>

</div>

<dt><dfn><<length>></dfn>

<dd>

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

<dt><dfn>''top''</dfn>

<dd>

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.

<dt><dfn>''right''</dfn>

<dd>

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.

<dt><dfn>''bottom''</dfn>

<dd>

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.

<dt><dfn>''left''</dfn>

<dd>

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.

<dt><dfn>''center''</dfn>

<dd>

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.

</dl>

<div class="example">

The following 'background' shorthand declarations use keywords

to set 'background-position' to the stated percentage values.

<pre>

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% */

</pre>

</div>

<div class="example">

In the example below, the (single) image is placed

in the lower-right corner of the viewport.

<pre>

body {

background-image: url("logo.png");

background-attachment: fixed;

background-position: 100% 100%;

background-repeat: no-repeat;

}

</pre>

</div>

<div class=example>

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:

<pre>background-position: right 3em bottom 10px</pre>

</div>

See [[#layering]] for how 'background-position' interacts

with other comma-separated background properties

to form each [=background image layer=].

<h4 id="bg-position-serialization">

Serialization of 'background-position' values</h4>

The [=specified value=] and [=computed value=] of the <<bg-position>> type

serialize exactly as defined in [[CSS-VALUES-4]] for <<position>>.

For 3-value productions

(which are not valid in <<position>>),

the [=specified value=] serialization

is identical to the equivalent 4-value syntax

except that the omitted offset remains omitted.

<h3 id="background-clip" oldids="the-background-clip">

Painting Area: the 'background-clip' property</h3>

<pre class="propdef">

Name: background-clip

Value: <<visual-box>>#

Initial: border-box

Applies to: all elements

Inherited: no

Percentages: N/A

Computed value: list, each item a keyword as specified

Animation type: repeatable list

</pre>

<wpt>

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/clip-rounded-corner.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_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

</wpt>

Determines the <dfn export>background painting area</dfn>,

which determines the area within which the background is painted.

Values have the following meanings:

<dl dfn-for=background-clip dfn-type=value>

<dt><dfn>border-box</dfn></dt>

<dd>

The background is painted within (clipped to) the

[=border box=].

<dt><dfn>padding-box</dfn></dt>

<dd>

The background is painted within (clipped to) the

[=padding box=].

<dt><dfn>content-box</dfn></dt>

<dd>

The background is painted within (clipped to) the

[=content box=].

</dl>

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 <em>behind</em> the border, if any.

See “Elaborate description of Stacking Contexts” in [[!CSS2]] Appendix E.

See [[#corner-shaping]] for how 'border-radius' affects

the shape of the [=background painting area=].