background CSS property

Try it

background: green;

background: content-box radial-gradient(crimson, skyblue);

background: no-repeat url("../../../../../../shared-assets/images/examples/lizard.png");

background: left 5% / 15% 60% repeat-x
  url("../../../../../../shared-assets/images/examples/star.png");

background:
  center / contain no-repeat
    url("../../../../../../shared-assets/images/examples/firefox-logo.svg"),
  #eeeeee 35% url("../../../../../../shared-assets/images/examples/lizard.png");

<section id="default-example">
  <div id="example-element"></div>
</section>

#example-element {
  min-width: 100%;
  min-height: 100%;
  padding: 10%;
}

Constituent properties

This property is a shorthand for the following CSS properties:

• background-attachment
• background-clip
• background-color
• background-image
• background-origin
• background-position
• background-repeat
• background-size

Syntax

/* Using a <background-color> */
background: green;

/* Using a <bg-image> and <repeat-style> */
background: url("test.jpg") repeat-y;

/* Using a <visual-box> and <'background-color'> */
background: border-box red;

/* A single image, centered and scaled */
background: no-repeat center/80% url("../img/image.png");

/* Global values */
background: inherit;
background: initial;
background: revert;
background: revert-layer;
background: unset;

Values

<attachment>

See background-attachment. Default: scroll.

<visual-box>

See background-clip and background-origin. Default: border-box and padding-box respectively.

<'background-color'>

See background-color. Default: transparent.

<bg-image>

See background-image. Default: none.

<bg-position>

See background-position. Default: 0% 0%.

<repeat-style>

See background-repeat. Default: repeat.

<bg-size>

See background-size. Default: auto.

Description

The background shorthand property enables you to declare all CSS background properties in a single declaration. The background lies underneath the content of an element. When you have multiple, comma-separated background values, each is a background layer that is painted on top of the previous layers.

The background property is specified as one or more background layers, separated by commas. Each layer may include zero, one, or two <visual-box> components and zero or one <attachment>, <bg-image>, <bg-position>, <bg-size>, and <repeat-style> components. If two <bg-position>, <bg-size>, or <repeat-style> components are specified, the first value is the horizontal value and the second value is the vertical value. If only a single value is set, that value is applied to both dimensions.

The <'background-color'> component may only be included in the last background layer specified.

Component properties not set in the background shorthand property value declaration are set to their default values.

Component property order

Because some of the component properties share value types, the order of those component properties within the shorthand is important.

The <bg-size> value may only be included immediately after <bg-position>, separated with the / character. For example: 10px 10px / 80% 80% means the background image is 80% as tall and as wide as the element, and will be positioned 10px from the top and 10px from the left of the element's top-left corner. Within the <bg-position>, if both values are lengths, or one is a length and the other is center, the first value refers to the horizontal position and the second value refers to the vertical position.

Each background layer can include zero, one, or two <visual-box> values. If only one value is included, it sets both background-origin and background-clip. If two values are present, the first occurrence specifies the background-origin and the second specifies the background-clip value. If no <visual-box> values are present, the background-origin defaults to padding-box and the background-clip defaults to border-box.

While there is no order requirement for the other background properties, the following order is recommended for consistency and legibility; remember that none of the values are required:

<bg-image> <bg-position> / <bg-size> <repeat-style> <attachment> <bg-clip> <bg-origin> <'background-color'>

The following background explicitly sets all the default values in this order:

background: none 0% 0% / auto auto repeat scroll border-box padding-box
  transparent;

The following three lines of CSS are equivalent to the above, even if the order differs:

background: none;
background: transparent;
background: repeat scroll 0% 0% / auto padding-box border-box none transparent;

Image painting order

If multiple comma-separated backgrounds are included, they create multiple background layers on top of one another. The first background in the list creates the top layer. If the top layer contains no transparent areas, this is the only layer that will be visible.

The last layer is the bottom layer. The background color is always included in this layer.

Body background applied to the entire document

If the document <html> :root element's computed background-image value is none and its background-color is transparent, the browser will transfer the background styles set on the <body> element onto the :root and treat the <body> as if background: initial were set. In other words, the <html> element gets all the background styles set on the <body> element, and the <body> element's background properties are set to their initial values.

Because of this behavior, the specification authors recommend setting your document's background styles in your body style block rather than your html style block. However, it's important to note that using containment disables this behavior. When the contain property is set to anything other than none on either the <html> or <body> element, the background property and any longhand components do not propagate from the <body> element to the root <html> element.

Formal definition

Formal syntax

background = 
  <bg-layer>#? , <final-bg-layer>  

<bg-layer> = 
  <bg-image>                      ||
  <bg-position> [ / <bg-size> ]?  ||
  <repeat-style>                  ||
  <attachment>                    ||
  <bg-clip>                       ||
  <visual-box>                    

<final-bg-layer> = 
  <bg-image>                      ||
  <bg-position> [ / <bg-size> ]?  ||
  <repeat-style>                  ||
  <attachment>                    ||
  <bg-clip>                       ||
  <visual-box>                    ||
  <'background-color'>            

<bg-image> = 
  <image>  |
  none     

<bg-position> = 
  <position>        |
  <position-three>  

<bg-size> = 
  [ <length-percentage [0,∞]> | auto ]{1,2}  |
  cover                                      |
  contain                                    

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

<attachment> = 
  scroll  |
  fixed   |
  local   

<bg-clip> = 
  <visual-box>             |
  [ border-area || text ]  

<visual-box> = 
  content-box  |
  padding-box  |
  border-box   

<background-color> = 
  <color>  

<image> = 
  <url>           |
  <image()>       |
  <image-set()>   |
  <cross-fade()>  |
  <element()>     |
  <gradient>      

<position> = 
  <position-one>   |
  <position-two>   |
  <position-four>  

<position-three> = 
  [ left | center | right ] && [ [ top | bottom ] <length-percentage> ]  |
  [ [ left | right ] <length-percentage> ] && [ top | center | bottom ]  

<length-percentage> = 
  <length>      |
  <percentage>  

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

<image()> = 
  image( <image-tags>? [ <image-src>? , <color>? ]! )  

<image-set()> = 
  image-set( <image-set-option># )  

<cross-fade()> = 
  cross-fade( <cf-image># )  

<element()> = 
  element( <id-selector> )  

<position-one> = 
  left                 |
  center               |
  right                |
  top                  |
  bottom               |
  x-start              |
  x-end                |
  y-start              |
  y-end                |
  block-start          |
  block-end            |
  inline-start         |
  inline-end           |
  <length-percentage>  

<position-two> = 
  [ left | center | right | x-start | x-end ] && [ top | center | bottom | y-start | y-end ]  |
  [ left | center | right | x-start | x-end | <length-percentage> ] [ top | center | bottom | y-start | y-end | <length-percentage> ]  |
  [ block-start | center | block-end ] && [ inline-start | center | inline-end ]  |
  [ start | center | end ]{2}                         

<position-four> = 
  [ [ left | right | x-start | x-end ] <length-percentage> ] && [ [ top | bottom | y-start | y-end ] <length-percentage> ]  |
  [ [ block-start | block-end ] <length-percentage> ] && [ [ inline-start | inline-end ] <length-percentage> ]  |
  [ [ start | end ] <length-percentage> ]{2}          

<image-tags> = 
  ltr  |
  rtl  

<image-src> = 
  <url>     |
  <string>  

<image-set-option> = 
  [ <image> | <string> ] [ <resolution> || type( <string> ) ]?  

<cf-image> = 
  [ <image> | <color> ]  &&
  <percentage [0,100]>?  

<id-selector> = 
  <hash-token>  

Accessibility

Browsers do not provide any special information on background images to assistive technology. This is important primarily for screen readers, as a screen reader will not announce its presence and therefore convey nothing to its users. If the image contains information critical to understanding the page's overall purpose, it is better to describe it semantically in the document.

• MDN Understanding WCAG, Guideline 1.1 explanations
• Understanding Success Criterion 1.1.1 | W3C Understanding WCAG 2.0

Examples

Setting backgrounds with color keywords and images

HTML

<p class="top-banner">
  Starry sky<br />
  Twinkle twinkle<br />
  Starry sky
</p>
<p class="warning">Here is a paragraph</p>
<p></p>

CSS

.warning {
  background: pink;
}

.top-banner {
  background: url("star-solid.gif") #9999ff repeat-y fixed;
}

Result

Specifications

Browser compatibility