CSS background-image playground

Educational background-image guide

How to compose background images and gradients

Choose an image, order its layers, and control how it fills the box. Learn background-image with native gradient, cropping, and pattern examples that are independent of the playground.

Back to the playground

Mental model

A background decorates an existing box: it creates no HTML element and contributes no dimensions to layout.

1. First image: in front
Painted over the others; transparent areas reveal what lies underneath.
2. Next image: behind
Each comma adds a background layer to the same box.
3. Base color: at the back
background-color sits below every image.

The first layer is closest to the contentStatic conceptual diagram, from front to back. Text and children are painted over the box background; images are not DOM nodes.

The box needs dimensions

An empty box can have zero height even when the image exists. Content, padding, aspect-ratio, or a minimum height must provide room to paint it.

Positioning and clipping are separate decisions

background-origin defines the reference area for size and position; its default is padding-box. background-clip defines where painting occurs; its default is border-box. Neither changes the element size.

background-image accepts none, url(), or generated images such as gradients. A solid color belongs in background-color. The playground tests one URL; the guide scenes add gradients and layers without expanding its controls.

Gradients as images

CSS computes these images without a file or intrinsic dimensions.

linear-gradient() distributes colors along a direction; 90deg points right. radial-gradient() grows from a center in a circle or ellipse. conic-gradient() travels through angles around a center: it is not a radial gradient.

Linear, radial, and conic

linear-gradient()

radial-gradient()

conic-gradient()

All three boxes use the same two colors. The first changes from left to right, the second from an offset point, and the third around its center. Labels describe each function.

Linear, radial, and conic

HTML

<div class="background-guide-gradients">
  <div>
    <p>linear-gradient()</p>
    <div class="background-guide-scene linear" aria-hidden="true"></div>
  </div>
  <div>
    <p>radial-gradient()</p>
    <div class="background-guide-scene radial" aria-hidden="true"></div>
  </div>
  <div>
    <p>conic-gradient()</p>
    <div class="background-guide-scene conic" aria-hidden="true"></div>
  </div>
</div>

CSS

:root {
  color-scheme: light dark;
}

.background-guide-gradients {
  display: flex;
  flex-wrap: wrap;
  gap: 1rem;

  > div {
    flex: 1 1 10rem;
    min-inline-size: 0;
    display: grid;
    align-content: start;
    gap: 1rem;
  }

  p {
    margin: 0;
    color: light-dark(oklch(0.22 0.01 95), oklch(0.95 0.01 95));
    font: 1rem/1.6 system-ui, sans-serif;
    overflow-wrap: anywhere;
  }

  .background-guide-scene {
    min-inline-size: 0;
    min-block-size: 10rem;
    border: 1px solid light-dark(oklch(0.84 0.01 95), oklch(0.36 0.024 260));
    background-color: light-dark(color-mix(in oklch, oklch(0.95 0.008 95) 98%, white), color-mix(in oklch, oklch(0.22 0.024 260) 86%, black));

    @media (forced-colors: active) {
      border-color: CanvasText;
    }
  }

  .linear {
    background-image: linear-gradient(90deg, light-dark(oklch(0.87 0.1 261), oklch(0.78 0.24 261)), light-dark(oklch(0.88 0.09 66), oklch(0.78 0.22 66)));
  }

  .radial {
    background-image: radial-gradient(circle at 30% 40%, light-dark(oklch(0.88 0.09 66), oklch(0.78 0.22 66)), light-dark(oklch(0.87 0.1 261), oklch(0.78 0.24 261)));
  }

  .conic {
    background-image: conic-gradient(from 0deg, light-dark(oklch(0.87 0.1 261), oklch(0.78 0.24 261)), light-dark(oklch(0.88 0.09 66), oklch(0.78 0.22 66)), light-dark(oklch(0.87 0.1 261), oklch(0.78 0.24 261)));
  }
}

Color stops set where each color appears. Two stops at the same position create a hard edge. repeating-linear-gradient(), repeating-radial-gradient(), and repeating-conic-gradient() repeat the gradient segment; background-repeat tiles the entire image. Without an explicit size, a gradient fills the positioning area.

Layers and painting order

Commas separate images; property lists follow the same order.

The first image is in front. An opaque layer covering the entire area hides subsequent layers. Use transparency, a different size, or background blending when several need to remain visible; z-index does not reorder these layers.

The same circle, in front or hidden

Circle first: visible

Opaque gradient first: circle hidden

On the left, the circle layer is transparent outside its center and reveals the gradient. On the right, the opaque gradient is painted in front and hides the circle; their sizes are swapped too.

The same circle, in front or hidden

HTML

<div class="background-guide-layers">
  <div>
    <p>Circle first: visible</p>
    <div class="background-guide-scene" aria-hidden="true"></div>
  </div>
  <div>
    <p>Opaque gradient first: circle hidden</p>
    <div class="background-guide-scene reversed" aria-hidden="true"></div>
  </div>
</div>

CSS

:root {
  color-scheme: light dark;
}

.background-guide-layers {
  display: flex;
  flex-wrap: wrap;
  gap: 1rem;

  > div {
    flex: 1 1 10rem;
    min-inline-size: 0;
    display: grid;
    align-content: start;
    gap: 1rem;
  }

  p {
    margin: 0;
    color: light-dark(oklch(0.22 0.01 95), oklch(0.95 0.01 95));
    font: 1rem/1.6 system-ui, sans-serif;
    overflow-wrap: anywhere;
  }

  .background-guide-scene {
    min-inline-size: 0;
    min-block-size: 10rem;
    border: 1px solid light-dark(oklch(0.84 0.01 95), oklch(0.36 0.024 260));
    background-color: light-dark(color-mix(in oklch, oklch(0.95 0.008 95) 98%, white), color-mix(in oklch, oklch(0.22 0.024 260) 86%, black));

    @media (forced-colors: active) {
      border-color: CanvasText;
    }
  }

  .background-guide-scene {
    background-image:
      radial-gradient(circle, light-dark(oklch(0.88 0.09 66), oklch(0.78 0.22 66)) 45%, transparent 46%),
      linear-gradient(90deg, light-dark(oklch(0.87 0.1 261), oklch(0.78 0.24 261)), light-dark(oklch(0.86 0.11 148), oklch(0.8 0.22 148)));
    background-size: 5rem 5rem, cover;
    background-position: center, center;
    background-repeat: no-repeat;
  }

  .reversed {
    background-image:
      linear-gradient(90deg, light-dark(oklch(0.87 0.1 261), oklch(0.78 0.24 261)), light-dark(oklch(0.86 0.11 148), oklch(0.8 0.22 148))),
      radial-gradient(circle, light-dark(oklch(0.88 0.09 66), oklch(0.78 0.22 66)) 45%, transparent 46%);
    background-size: cover, 5rem 5rem;
  }
}

background-size and background-position are assigned by index. A shorter list repeats to cover the layers: no-repeat applies to both here. A longer list has unused extra values. background-color is a single color, beneath all layers.

Size and position

First decide whether filling the box or keeping the entire image matters more.

cover preserves the ratio and fills the area, cropping when proportions differ. contain keeps the whole image and may leave empty space. 100% auto sets the width and preserves the ratio; 100% 100% sets both axes and can distort it. auto uses intrinsic dimensions when they exist.

A 2:1 illustration inside a square box

cover

contain

100% 100%

cover crops the sides; contain shows the entire illustration with space above and below; 100% 100% stretches the image and makes the sun oval. All three use the same decorative SVG with explicit dimensions and no repeat.

A 2:1 illustration inside a square box

HTML

<div class="background-guide-sizing">
  <div>
    <p>cover</p>
    <div class="background-guide-scene cover" aria-hidden="true"></div>
  </div>
  <div>
    <p>contain</p>
    <div class="background-guide-scene contain" aria-hidden="true"></div>
  </div>
  <div>
    <p>100% 100%</p>
    <div class="background-guide-scene stretch" aria-hidden="true"></div>
  </div>
</div>

CSS

:root {
  color-scheme: light dark;
}

.background-guide-sizing {
  display: flex;
  flex-wrap: wrap;
  gap: 1rem;

  > div {
    flex: 1 1 10rem;
    min-inline-size: 0;
    display: grid;
    align-content: start;
    gap: 1rem;
  }

  p {
    margin: 0;
    color: light-dark(oklch(0.22 0.01 95), oklch(0.95 0.01 95));
    font: 1rem/1.6 system-ui, sans-serif;
    overflow-wrap: anywhere;
  }

  .background-guide-scene {
    min-inline-size: 0;
    min-block-size: 10rem;
    border: 1px solid light-dark(oklch(0.84 0.01 95), oklch(0.36 0.024 260));
    background-color: light-dark(color-mix(in oklch, oklch(0.95 0.008 95) 98%, white), color-mix(in oklch, oklch(0.22 0.024 260) 86%, black));

    @media (forced-colors: active) {
      border-color: CanvasText;
    }
  }

  .background-guide-scene {
    inline-size: min(100%, 12rem);
    aspect-ratio: 1;
    min-block-size: 0;
  }

  .cover {
    background-image: url("data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20width%3D%22240%22%20height%3D%22120%22%20viewBox%3D%220%200%20240%20120%22%20preserveAspectRatio%3D%22none%22%3E%3Cpath%20fill%3D%22%23dbeafe%22%20d%3D%22M0%200h240v120H0z%22%2F%3E%3Ccircle%20fill%3D%22%23fb923c%22%20cx%3D%22180%22%20cy%3D%2232%22%20r%3D%2218%22%2F%3E%3Cpath%20fill%3D%22%23166534%22%20d%3D%22m0%20120%2065-95%2070%2095z%22%2F%3E%3Cpath%20fill%3D%22%232563eb%22%20d%3D%22m90%20120%2075-65%2075%2065z%22%2F%3E%3C%2Fsvg%3E");
    background-position: center;
    background-size: cover;
    background-repeat: no-repeat;
    background-attachment: scroll;
  }

  .contain {
    background-image: url("data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20width%3D%22240%22%20height%3D%22120%22%20viewBox%3D%220%200%20240%20120%22%20preserveAspectRatio%3D%22none%22%3E%3Cpath%20fill%3D%22%23dbeafe%22%20d%3D%22M0%200h240v120H0z%22%2F%3E%3Ccircle%20fill%3D%22%23fb923c%22%20cx%3D%22180%22%20cy%3D%2232%22%20r%3D%2218%22%2F%3E%3Cpath%20fill%3D%22%23166534%22%20d%3D%22m0%20120%2065-95%2070%2095z%22%2F%3E%3Cpath%20fill%3D%22%232563eb%22%20d%3D%22m90%20120%2075-65%2075%2065z%22%2F%3E%3C%2Fsvg%3E");
    background-position: center;
    background-size: contain;
    background-repeat: no-repeat;
    background-attachment: scroll;
  }

  .stretch {
    background-image: url("data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20width%3D%22240%22%20height%3D%22120%22%20viewBox%3D%220%200%20240%20120%22%20preserveAspectRatio%3D%22none%22%3E%3Cpath%20fill%3D%22%23dbeafe%22%20d%3D%22M0%200h240v120H0z%22%2F%3E%3Ccircle%20fill%3D%22%23fb923c%22%20cx%3D%22180%22%20cy%3D%2232%22%20r%3D%2218%22%2F%3E%3Cpath%20fill%3D%22%23166534%22%20d%3D%22m0%20120%2065-95%2070%2095z%22%2F%3E%3Cpath%20fill%3D%22%232563eb%22%20d%3D%22m90%20120%2075-65%2075%2065z%22%2F%3E%3C%2Fsvg%3E");
    background-position: center;
    background-size: 100% 100%;
    background-repeat: no-repeat;
    background-attachment: scroll;
  }
}

background-position aligns corresponding points of the image and area: 50% 50% centers both. Percentage offsets use the remaining space, not just the box width. If the image fills an entire axis, changing its percentage on that axis does not move it. With cover, adjust position to choose which part survives cropping.

Repeating and a decorative recipe

A small tile can fill a container that grows with its content.

repeat is the initial value; no-repeat paints one copy. repeat-x and repeat-y tile on one axis. space preserves size and distributes gaps; round resizes tiles to fit complete copies. With space, position on that axis only matters when two copies cannot fit.

A dot pattern with text on an opaque surface

The pattern is decorative. This text remains readable HTML content.

The transparent 32 × 32 SVG tiles around the paragraph. Its opaque background separates text from the pattern. If decoration disappears, the content and base color remain.

A dot pattern with text on an opaque surface

HTML

<div class="background-guide-pattern">
  <p>The pattern is decorative. This text remains readable HTML content.</p>
</div>

CSS

:root {
  color-scheme: light dark;
}

.background-guide-pattern {
  padding: 2rem;
  background-color: light-dark(color-mix(in oklch, oklch(0.95 0.008 95) 98%, white), color-mix(in oklch, oklch(0.22 0.024 260) 86%, black));
  background-image: url("data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20width%3D%2232%22%20height%3D%2232%22%20viewBox%3D%220%200%2032%2032%22%3E%3Ccircle%20fill%3D%22%232563eb%22%20cx%3D%2216%22%20cy%3D%2216%22%20r%3D%223%22%2F%3E%3C%2Fsvg%3E");
  background-position: top left;
  background-size: auto;
  background-repeat: repeat;
  background-attachment: scroll;

  p {
    margin: 0;
    padding: 1rem;
    color: light-dark(oklch(0.22 0.01 95), oklch(0.95 0.01 95));
    background-color: light-dark(color-mix(in oklch, oklch(0.95 0.008 95) 98%, white), color-mix(in oklch, oklch(0.22 0.024 260) 86%, black));
    font: 1rem/1.6 system-ui, sans-serif;
    overflow-wrap: anywhere;
  }

  @media (forced-colors: active) {
    background-image: none;
    border: 1px solid CanvasText;
  }
}

In the background shorthand, size follows position and a slash: center / cover no-repeat. The declaration resets omitted properties; a later background can erase a previous image or color. With multiple layers, a color can only appear in the last shorthand layer.

What is it attached to during scrolling?

scroll moves with the box, but not with content scrolling inside it. local is attached to scrollable content. fixed uses the viewport as its reference; it does not create position: fixed or automatic parallax. Compare document scrolling with preview scrolling and check fixed on your target devices.

Decorative background or content image

The decision depends on meaning, not on whether the image visually fills a card.

Optional decoration

Use background-image for a texture, halo, or image that adds no essential information. The message should still make sense without it. A CSS background has no alt attribute; a visible label or aria-label does not automatically turn decoration into a semantic image.

An image conveying information

Use <img> for a product photograph, diagram, or relevant visual information, with alt suited to its context. Use alt="" when the <img> is purely decorative. width and height reserve its ratio; srcset/sizes or <picture> adapt the resource. object-fit: cover can provide visual cropping while preserving HTML semantics.

Text, loading, and preferences

Check contrast over the final result and across responsive positions; an image or gradient does not guarantee readability. Keep a base color and, when needed, an opaque text surface. Forced colors remove gradients; URL-based backgrounds may remain. Content should still make sense.

background-size changes painted size, not downloaded bytes. Serve an optimized image for large decorative assets; image-set() offers resolution or format alternatives for the browser to select. Check that function separately and keep an earlier url() declaration if you need to cover browsers that do not accept it.

Common mistakes

Check the box and cascade before replacing the image.

The image is invisible

Expected result: A background inside an empty box.
Cause: The box has no height, the URL fails, or a later declaration changes the background.
Solution: Inspect dimensions and computed CSS; check the request and keep a base color.

An important part is missing

Expected result: A filled box and a completely visible image.
Cause: cover must crop when proportions differ.
Solution: Choose contain, change the box ratio, or position the point of interest.

contain produces tiles

Expected result: One complete image.
Cause: background-size does not change the initial repeat value.
Solution: Add background-repeat: no-repeat when you want one copy.

Changing color removes the background

Expected result: Keep the image and update only the base color.
Cause: background: <color> resets background-image to none and other omitted properties.
Solution: Change background-color or write a complete shorthand with every required layer.

Information exists only in the background

Expected result: Everyone receives the same message.
Cause: CSS decoration provides no text alternative to assistive technology.
Solution: Move information into HTML and use <img> with alt when the image is content.

Support and compatibility

Support for background-image does not certify every value accepted by <image>.

Core background-image, multiple layers, and classic adjustments have established support. These examples run native CSS; seeing them in this browser does not validate every engine or mobile case.

Check value-specific tables for conic-gradient(), image-set(), color interpolation spaces, or background-attachment: fixed. Functions such as cross-fade() or element() do not inherit the general availability of the property and are outside these recipes.

A failed image is not replaced by the color as another image: it reveals what is painted underneath. Keep background-color, HTML text, and a useful design without decoration; apply @supports or progressive declarations when introducing syntax with different support.