Runnable CSS Docs: Background Image

Q: How do I add a background image in CSS?

Use background-image: url("photo.jpg"); on the element. The path is relative to the CSS file (or to the page, for a style attribute or element). Give the element a size, because a background never makes an empty element grow.

Q: How do I make a background image cover the whole element?

Use background-size: cover; with background-position: center;. The image scales to fill the box completely, keeping its proportions, and the overflow is cropped.

Q: What is the difference between cover and contain?

cover fills the whole box and crops what does not fit. contain shows the whole image and leaves empty space on two sides when the proportions differ.

Q: How do I stop a background image from repeating?

Add background-repeat: no-repeat;. By default a background image tiles in both directions to fill the element.

Q: Why is my background image not showing?

The usual causes are a wrong path in url() (it is relative to the CSS file), an element with no height because it has no content, or a later background shorthand that reset the image.

How to add a background image

background-image paints an image behind the element's content, padding and border. By default it starts at the top left corner of the padding box, keeps its natural size and repeats to fill the box:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Background image</title>
  <style>
    body { font-family: system-ui, sans-serif; }
    .dots {
      /* a 24x24 image: one blue dot */
      background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='24' height='24'%3E%3Ccircle cx='12' cy='12' r='4' fill='%232563eb'/%3E%3C/svg%3E");
      height: 120px;
      padding: 16px;
      border: 2px solid #111827;
      font-weight: 600;
    }
  </style>
</head>
<body>
  <div class="dots">One 24px image, repeated to fill the box</div>
</body>
</html>

In a real project the url() points at a file: url("images/hero.jpg"). The path is relative to the stylesheet that contains it (or to the page, for a <style> element). The examples on this page use small SVG images written inline as data: URLs so they run anywhere.

Two things to know from the start:

A background does not give an element size. An empty div with a background image is 0px tall. Give it content, padding, a height or an aspect-ratio.
A background image is decoration. Screen readers skip it and it has no alt text. An image that carries meaning belongs in an <img> element.

background-size: cover, contain and lengths

background-size scales the image. The two keywords keep its proportions:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>cover vs contain</title>
  <style>
    body { font-family: system-ui, sans-serif; font-size: 14px; }
    .row { display: flex; gap: 12px; flex-wrap: wrap; }
    .box {
      --landscape: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='400' height='200' viewBox='0 0 400 200'%3E%3Crect width='400' height='200' fill='%23bfdbfe'/%3E%3Ccircle cx='320' cy='50' r='24' fill='%23f59e0b'/%3E%3Cpath d='M0 200L120 70L220 200Z' fill='%2316a34a'/%3E%3Cpath d='M140 200L270 90L400 200Z' fill='%2315803d'/%3E%3C/svg%3E");
      width: 160px; height: 160px;
      background: var(--landscape) center / auto no-repeat, #e5e7eb;
      border: 2px solid #111827;
    }
    .cover { background-size: cover; }
    .contain { background-size: contain; }
    .stretch { background-size: 100% 100%; }
  </style>
</head>
<body>
  <div class="row">
    <div><div class="box"></div>auto (400x200, cropped)</div>
    <div><div class="box cover"></div>cover</div>
    <div><div class="box contain"></div>contain</div>
    <div><div class="box stretch"></div>100% 100% (distorted)</div>
  </div>
</body>
</html>

The image is twice as wide as it is tall and each box is square.

Value	Result
`auto` (default)	The image's own size
`cover`	Scales until the box is completely filled; the excess is cropped
`contain`	Scales until the whole image fits; gray bands remain on two sides
`200px`	200px wide, height in proportion
`50% auto`	Half the box's width, height in proportion
`100% 100%`	Exactly the box's size; distorts the image if the proportions differ

cover is the usual choice for hero banners and cards. contain is for logos and illustrations that must never be cut off.

background-position and background-repeat

background-position places the image inside the box, with keywords (top, center, bottom, left, right), percentages or lengths. background-repeat controls tiling. Try some values:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Position and repeat</title>
  <style>
    body { font-family: system-ui, sans-serif; }
    #box {
      height: 140px; margin-top: 10px;
      border: 2px solid #111827;
      background-color: #f3f4f6;
      background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='24' height='24'%3E%3Ccircle cx='12' cy='12' r='4' fill='%232563eb'/%3E%3C/svg%3E");
      background-size: 48px;
    }
    label { display: block; margin-top: 6px; }
  </style>
</head>
<body>
  <label>background-position: <input id="pos" value="center" size="18"></label>
  <label>background-repeat: <input id="rep" value="no-repeat" size="18"></label>
  <div id="box"></div>
  <script>
    const box = document.getElementById('box');
    const pos = document.getElementById('pos');
    const rep = document.getElementById('rep');
    const show = () => {
      box.style.backgroundPosition = pos.value;
      box.style.backgroundRepeat = rep.value;
    };
    pos.addEventListener('input', show);
    rep.addEventListener('input', show);
    show();
  </script>
</body>
</html>

Try positions top right, bottom 10px right 20px and 25% 75%, and repeat values repeat-x, repeat-y, space (tiles with gaps so none are cut) and round (tiles resized so a whole number fits).

Layering: several backgrounds and a text overlay

background-image takes a comma-separated list. The first layer is drawn on top. The common use is a semi-transparent gradient over a photo, so white text stays readable:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Overlay</title>
  <style>
    body { font-family: system-ui, sans-serif; margin: 0; }
    .hero {
      --landscape: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='400' height='200' viewBox='0 0 400 200'%3E%3Crect width='400' height='200' fill='%23bfdbfe'/%3E%3Ccircle cx='320' cy='50' r='24' fill='%23f59e0b'/%3E%3Cpath d='M0 200L120 70L220 200Z' fill='%2316a34a'/%3E%3Cpath d='M140 200L270 90L400 200Z' fill='%2315803d'/%3E%3C/svg%3E");
      background-image:
        linear-gradient(rgb(17 24 39 / 10%), rgb(17 24 39 / 75%)),
        var(--landscape);
      background-size: cover;
      background-position: center;
      aspect-ratio: 16 / 7;
      display: flex; align-items: end;
      padding: 20px; box-sizing: border-box;
      color: white;
    }
    h1 { margin: 0; font-size: 32px; }
  </style>
</head>
<body>
  <div class="hero" id="hero"><h1>Readable over an image</h1></div>
</body>
</html>

aspect-ratio gives the empty box a height, and background-size: cover applies to both layers. For more gradient recipes, see CSS gradients.

The background shorthand

background sets every background property in one line. Size must come right after position, separated by a slash, and the color goes in the last layer:

.hero {
  background: url("hero.jpg") center / cover no-repeat, #1f2937;
}
/* the same as */
.hero {
  background-image: url("hero.jpg");
  background-position: center;
  background-size: cover;
  background-repeat: no-repeat;
  background-color: #1f2937;
}

The fallback color shows while the image loads, and if it fails. Any property you leave out of the shorthand is reset to its default, so put the shorthand first and individual properties after it.

Other background properties

Property	What it does
`background-attachment: fixed`	The image stays put while the page scrolls (ignored on iOS Safari)
`background-origin`	Whether position starts at the border, padding or content edge
`background-clip`	Where the background is painted, including `text` to fill letters
`background-blend-mode`	Blends layers together, like `multiply`

Common mistakes

A wrong path. url() in a stylesheet is relative to the CSS file, not to the HTML page.
An empty element. It has no height, so the image has nowhere to show.
Forgetting no-repeat with contain or a small image: it tiles.
Stretching with 100% 100% when you meant cover.
Important images as backgrounds. Use <img> with alt text for content; backgrounds are invisible to screen readers.
Missing quotes around a data: URL containing spaces or quotes. Always write url("...").

Frequently Asked Questions

How do I add a background image in CSS?

Use background-image: url("photo.jpg"); on the element. The path is relative to the CSS file (or to the page, for a style attribute or <style> element). Give the element a size, because a background never makes an empty element grow.

How do I make a background image cover the whole element?

Use background-size: cover; with background-position: center;. The image scales to fill the box completely, keeping its proportions, and the overflow is cropped.

What is the difference between cover and contain?

cover fills the whole box and crops what does not fit. contain shows the whole image and leaves empty space on two sides when the proportions differ.

How do I stop a background image from repeating?

Add background-repeat: no-repeat;. By default a background image tiles in both directions to fill the element.

Why is my background image not showing?

The usual causes are a wrong path in url() (it is relative to the CSS file), an element with no height because it has no content, or a later background shorthand that reset the image.

Related concepts