CSS background-image: a practical guide

Eight properties control how a background image renders. Learn what each one does, which defaults apply, and where the shorthand quietly resets your values.

6 min read
CSS background-image: a practical guide
In short
  • background-size: cover fills the box and crops; contain shows the whole image and may leave gaps.
  • The shorthand resets every property you leave out, including background-color.
  • In the shorthand, size must follow position after a slash: center / cover.
  • With multiple layers, the first one listed paints on top. Color goes only in the last layer.
0% 0%Default background-position
8Longhands set by the shorthand
1Layers that may hold a color

The property set at a glance

A CSS background is a stack of layers painted behind an element's content. Each layer is described by a group of longhand properties. The shorthand background sets all of them at once.

PropertyInitial valueWhat it controls
background-imagenoneThe image or gradient to paint
background-sizeautoHow large each image is drawn
background-position0% 0%Where the image is anchored
background-repeatrepeatWhether and how it tiles
background-attachmentscrollHow it behaves when content scrolls
background-originpadding-boxThe box used for positioning
background-clipborder-boxThe box the painting is cut to
background-colortransparentA solid fill under all image layers

Notice the defaults. An image with no other settings sits in the top left corner at its natural size and repeats in both directions. That is right for small tiles and wrong for most photos.

Size: cover, contain and auto

background-size decides how the image maps onto the box. Three keywords cover most cases.

  • cover scales the image until it fills the whole box. The aspect ratio is kept, so one axis overflows and gets cropped.
  • contain scales the image until it fits entirely inside the box. Nothing is cropped, but empty bands may appear, and those bands repeat unless you stop them.
  • auto draws the image at its intrinsic size. A 1600×1200 file stays 1600 by 1200 CSS pixels.

You can also pass lengths or percentages. background-size: 50% auto makes the image half the box width and keeps its ratio. Percentages refer to the positioning area, which is set by background-origin.

For a full bleed hero, cover is the usual choice. A photographic set such as the bokeh backgrounds crops well because it has no single focal point that must stay visible.

9 bokeh backgrounds, original variant

Position and repeat

background-position takes one to four values. Keywords like center or right bottom are readable. Percentages align a point in the image with the same point in the box, so 75% 50% lines up the image's 75% mark with the box's 75% mark. Edge offsets work too: right 24px bottom 16px.

With cover, position decides which part of the image survives the crop. Set it to the area you care about. A city skyline usually wants center bottom so the buildings never get cut off.

background-repeat accepts repeat, no-repeat, repeat-x, repeat-y, round and space. Two values set the axes separately. For any photo larger than its box, add no-repeat anyway. It costs nothing and prevents a visible tile edge when the box grows taller than expected.

Attachment, origin and clip

background-attachment has three values. scroll fixes the background to the element, so it moves with the page. fixed fixes it to the viewport, which creates the classic parallax look. local fixes it to the element's scrolled content, which matters for scrollable boxes.

Use fixed with care. Many mobile browsers ignore it and treat it as scroll. On desktop it can force extra repaints during scrolling. Test it before you build a layout around it.

background-origin sets the box used for position and percentage sizes: border-box, padding-box or content-box. background-clip sets where painting stops. It accepts the same three boxes, and text as well, which paints the background only inside the glyphs. Pair background-clip: text with a transparent text color, and keep a solid fallback color for readability.

Linen fabric texture, deep variant

Shorthand pitfalls

The background shorthand is compact, but it has rules that surprise people.

  1. It resets what you omit. Writing background: url(bg.jpg) after background-color: #0b1b33 sets the color back to transparent.
  2. Size needs a slash. Size can only appear right after position, separated by /. center / cover is valid. cover center is not.
  3. Box keywords are positional. One box keyword sets both origin and clip. With two, the first is origin and the second is clip.
  4. One invalid token drops the whole line. The browser then keeps whatever background applied before.

A safe pattern is to use the shorthand once for the base, then override single longhands later. Always include a color that matches the image's average tone. It shows while the file loads and if it fails.

.hero {
  background: #0b1b33 url("wavy-lines.jpg") center / cover no-repeat;
}
.hero--light {
  background-position: center top;
}

Multiple layers

Each background property accepts a comma separated list. Every item in the list is a layer. The first layer paints on top, the last at the bottom. Values line up by index, so the second size applies to the second image.

The most common use is a gradient over a photo. The gradient darkens the image so text stays readable, and you keep a single element.

.banner {
  background:
    linear-gradient(rgb(0 0 0 / 0.55), rgb(0 0 0 / 0.15)),
    url("concrete-wall.jpg") center / cover no-repeat,
    #6b6b6b;
}

Two rules apply. A color is only valid in the final layer. If a list is shorter than the number of images, the browser repeats it to fill the gap. If it is longer, the extra values are ignored.

Layers also let you mix a texture with a flat tint. A linen fabric texture under a semi transparent brand color gives a surface with depth but a controlled tone. Browse more options in background textures and abstract backgrounds.

Gradients, and a final checklist

In CSS, a gradient is an image value. That means linear-gradient(), radial-gradient() and conic-gradient() go in background-image, not in background-color. They obey size, position and repeat exactly like a file does.

This has practical uses. A gradient has no intrinsic size, so by default it fills the positioning area. Give it a small background-size and it tiles, which is how simple stripes and grids are drawn without any download. repeating-linear-gradient() does the same in one value.

Gradients also cost nothing on the network. Use one as a placeholder behind a large photo, matched to the photo's main colors. If the image is slow, the page still looks intentional. If the image fails, the text over it keeps a predictable background.

Treat every layer as an image with its own size, position and repeat. Most background bugs come from forgetting that a gradient follows the same rules.

Checklist before you ship

  • Set a background-color close to the image's average tone.
  • Add no-repeat to every photo that should not tile.
  • Choose a background-position that protects the important part of the image.
  • Check the crop at narrow and wide viewports, because cover crops differently at each width.
  • Measure text contrast against the busiest area of the image, not the average.
  • Keep decorative images in CSS and meaningful images in HTML with alt text.

The last point matters for accessibility. Screen readers do not announce CSS backgrounds. If an image carries information, it belongs in an <img> element.

Questions

What is the difference between cover and contain?

cover scales the image until it fills the whole box and crops the overflow. contain scales it until the entire image fits inside, which can leave empty bands. Both keep the original aspect ratio, so neither one stretches the picture.

Why did my background color disappear?

The background shorthand resets every property you leave out to its initial value. If you write background with only an image after setting a color, the color becomes transparent. Put the color in the same shorthand, or set the longhand after it.

Does background-attachment: fixed work on phones?

Support is unreliable. Many mobile browsers treat fixed as scroll to keep scrolling smooth. If parallax matters to the design, test on real devices and make sure the layout still works when the background simply scrolls with the page.

Which layer paints on top?

The first one in the comma separated list. Layers paint from last to first, so the last image sits at the bottom, and the background color, if present, sits under all of them.

Keep reading

Built for the web.
Free to download.