Codectionary / Developer documentation / CSS

Background Properties

Background properties control an element's background color and image. background-image sets one or more images, background-size controls their scaling, background-position controls placement, and background-repeat controls tiling. Multiple backgrounds can be layered by comma-separating values.

Syntax

background-image: url();
background-size: cover | contain | length;
background-position: value;

Examples

A Full-Bleed Cover Image

The classic hero-image pattern.

/* Demo setup: sizing, structure or neutral surfaces. */
.hero,.overlay-hero{min-height:15rem;display:grid;align-content:center;padding:1.5rem;color:white;text-shadow:0 1px 3px #000}

.hero {
  background-image: url("data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20width%3D%22480%22%20height%3D%22240%22%20viewBox%3D%220%200%20480%20240%22%3E%3Crect%20width%3D%22480%22%20height%3D%22240%22%20fill%3D%22%23e0f2fe%22%2F%3E%3Ccircle%20cx%3D%22365%22%20cy%3D%2255%22%20r%3D%2230%22%20fill%3D%22%23fbbf24%22%2F%3E%3Cpath%20d%3D%22M0%20240%20135%2055%20280%20240%22%20fill%3D%22%230f766e%22%2F%3E%3Cpath%20d%3D%22m150%20240%20155-150%20175%20150%22%20fill%3D%22%235b21b6%22%2F%3E%3Ctext%20x%3D%2220%22%20y%3D%22218%22%20fill%3D%22white%22%20font-size%3D%2224%22%20font-family%3D%22sans-serif%22%3EOriginal%20landscape%3C%2Ftext%3E%3C%2Fsvg%3E");
  background-size: cover;       /* fills the box, cropping as needed */
  background-position: center;   /* keeps the image centered while cropping */
  background-repeat: no-repeat;
}
  1. The background uses the included original landscape rather than a missing banner.jpg file.
  2. cover preserves the image ratio and crops it to fill the region; it does not stretch both dimensions independently.
  3. Resize the preview and change background-position to see which part is cropped.
HTML used by this example
<section class="hero"><h2>Background cropping study</h2><p>Watch the mountain and sun as the region changes width.</p></section>

Layering Multiple Backgrounds

Combining a gradient overlay with an image, comma-separated from front to back.

/* Demo setup: sizing, structure or neutral surfaces. */
.hero,.overlay-hero{min-height:15rem;display:grid;align-content:center;padding:1.5rem;color:white;text-shadow:0 1px 3px #000}

.overlay-hero {
  background-image:
    linear-gradient(rgba(0,0,0,0.4), rgba(0,0,0,0.4)),
    url("data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20width%3D%22480%22%20height%3D%22240%22%20viewBox%3D%220%200%20480%20240%22%3E%3Crect%20width%3D%22480%22%20height%3D%22240%22%20fill%3D%22%23e0f2fe%22%2F%3E%3Ccircle%20cx%3D%22365%22%20cy%3D%2255%22%20r%3D%2230%22%20fill%3D%22%23fbbf24%22%2F%3E%3Cpath%20d%3D%22M0%20240%20135%2055%20280%20240%22%20fill%3D%22%230f766e%22%2F%3E%3Cpath%20d%3D%22m150%20240%20155-150%20175%20150%22%20fill%3D%22%235b21b6%22%2F%3E%3Ctext%20x%3D%2220%22%20y%3D%22218%22%20fill%3D%22white%22%20font-size%3D%2224%22%20font-family%3D%22sans-serif%22%3EOriginal%20landscape%3C%2Ftext%3E%3C%2Fsvg%3E");
  background-size: cover;
}
  1. The background uses the included original landscape rather than a missing banner.jpg file.
  2. cover preserves the image ratio and crops it to fill the region; it does not stretch both dimensions independently.
  3. The first gradient layer sits over the image and changes its visible contrast.
HTML used by this example
<section class="overlay-hero"><h2>Background cropping study</h2><p>Watch the mountain and sun as the region changes width.</p></section>

Parameters and values

  • background-color (color): Solid background fill, shows if the image fails to load
  • background-image (url() | gradient): One or more layered background images
  • background-size (cover | contain | length): How the image is scaled within the element
  • background-position (keyword | length): Where the image is placed within the element
  • background-repeat (repeat | no-repeat | repeat-x | repeat-y): Whether/how the image tiles

Best practices

  • Always set a background-color as a fallback alongside background-image, in case the image fails to load or is still loading
  • Use background-size: cover for full-bleed hero images, and contain when the entire image must always be visible without cropping
  • Layer a semi-transparent gradient over a background image to ensure text placed on top remains readable
  • Prefer an actual <img> element with alt text over a CSS background-image when the image is meaningful content, not decoration

Browser compatibility

chrome
Yes
firefox
Yes
safari
Yes
edge
Yes

These are the existing reference’s support labels, not tested minimum versions. Individual values and APIs can have different support. Check the linked specification before choosing a browser target.

CSS specifications (modules)

Specifications & further reading