Playground de background-image en CSS

Guía educativa de background-image

Cómo componer imágenes y gradientes de fondo

Elige la imagen, ordena sus capas y ajusta cómo ocupa la caja. Aprende background-image con ejemplos nativos de gradientes, recorte y patrones, independientes del playground.

Volver al playground

Modelo mental

Un fondo decora una caja existente: no crea un elemento HTML ni aporta dimensiones al layout.

1. Primera imagen: delante
Se pinta sobre las demás; sus zonas transparentes dejan ver lo que hay debajo.
2. Siguiente imagen: detrás
Cada coma añade una capa de fondo a la misma caja.
3. Color base: al fondo
background-color queda debajo de todas las imágenes.

La primera capa está más cerca del contenidoEsquema conceptual estático, de delante hacia atrás. El texto y los hijos se pintan sobre el fondo de la caja; las imágenes no son nodos del DOM.

La caja necesita tamaño

Una caja vacía puede tener altura cero aunque la imagen exista. El contenido, el padding, aspect-ratio o un mínimo de altura deben proporcionar espacio para pintarla.

Posicionar y recortar son decisiones distintas

background-origin define el área de referencia para tamaño y posición; por defecto es padding-box. background-clip define dónde se pinta; por defecto es border-box. No cambian el tamaño del elemento.

background-image acepta none, url() o imágenes generadas como gradientes. Un color sólido pertenece a background-color. El playground prueba una URL; las escenas de esta guía añaden gradientes y capas sin ampliar sus controles.

Gradientes como imágenes

Son imágenes calculadas por CSS, sin un archivo ni dimensiones intrínsecas.

linear-gradient() distribuye colores a lo largo de una dirección; 90deg avanza hacia la derecha. radial-gradient() crece desde un centro con forma circular o elíptica. conic-gradient() recorre ángulos alrededor de un centro: no es un degradado radial.

Lineal, radial y cónico

linear-gradient()

radial-gradient()

conic-gradient()

Las tres cajas usan los mismos dos colores. La primera cambia de izquierda a derecha, la segunda desde un punto desplazado y la tercera alrededor del centro. Los rótulos describen cada función.

Lineal, radial y cónico

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)));
  }
}

Los color stops fijan dónde aparece cada color. Dos stops en la misma posición crean un corte duro. repeating-linear-gradient(), repeating-radial-gradient() y repeating-conic-gradient() repiten el tramo del gradiente; background-repeat repite la imagen completa. Sin un tamaño explícito, un gradiente ocupa el área de posicionamiento.

Capas y orden de pintura

Las comas separan imágenes; las listas de propiedades siguen el mismo orden.

La primera imagen queda delante. Una capa opaca que cubre toda el área oculta las siguientes. Usa transparencia, otro tamaño o mezcla de fondos cuando necesites ver varias a la vez; z-index no reordena estas capas.

El mismo círculo, delante o escondido

Círculo primero: visible

Gradiente opaco primero: círculo oculto

A la izquierda, la capa del círculo es transparente fuera de su centro y deja ver el gradiente. A la derecha, el gradiente opaco se pinta delante y tapa el círculo; también se intercambian sus tamaños.

El mismo círculo, delante o escondido

HTML

<div class="background-guide-layers">
  <div>
    <p>Círculo primero: visible</p>
    <div class="background-guide-scene" aria-hidden="true"></div>
  </div>
  <div>
    <p>Gradiente opaco primero: círculo oculto</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 y background-position se asignan por índice. Una lista más corta se repite hasta cubrir las capas: aquí no-repeat sirve para ambas. Una lista más larga tiene valores sobrantes que no se usan. background-color es único, debajo de todas las capas.

Tamaño y posición

Primero decide si prefieres llenar la caja o conservar toda la imagen.

cover conserva la proporción y cubre el área, con recorte si las proporciones difieren. contain conserva la imagen completa y puede dejar espacio libre. 100% auto fija el ancho y mantiene la proporción; 100% 100% fija ambos ejes y puede deformarla. auto usa las dimensiones intrínsecas cuando existen.

Una ilustración 2:1 dentro de una caja cuadrada

cover

contain

100% 100%

cover recorta los lados; contain muestra toda la ilustración con espacio arriba y abajo; 100% 100% estira la imagen y vuelve ovalado el sol. Los tres casos usan el mismo SVG decorativo con dimensiones explícitas y sin repetición.

Una ilustración 2:1 dentro de una caja cuadrada

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 alinea puntos equivalentes de la imagen y del área: 50% 50% centra ambas. El desplazamiento porcentual usa el espacio sobrante, no solo el ancho de la caja. Si la imagen ocupa todo un eje, cambiar el porcentaje de ese eje no la mueve. Con cover, ajusta la posición para decidir qué parte sobrevive al recorte.

Repetición y una receta decorativa

Un mosaico pequeño puede rellenar un contenedor que crece con su contenido.

repeat es el valor inicial; no-repeat pinta una sola copia. repeat-x y repeat-y repiten en un eje. space conserva el tamaño y reparte huecos; round ajusta el tamaño para encajar copias completas. Con space, la posición de ese eje solo interviene cuando no caben dos copias.

Patrón de puntos con texto sobre una superficie opaca

El patrón es decorativo. Este texto sigue siendo contenido HTML legible.

El SVG transparente de 32 × 32 se repite alrededor del párrafo. Su fondo opaco separa el texto del patrón. Si desaparece la decoración, el contenido y el color base permanecen.

Patrón de puntos con texto sobre una superficie opaca

HTML

<div class="background-guide-pattern">
  <p>El patrón es decorativo. Este texto sigue siendo contenido HTML legible.</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;
  }
}

En el shorthand background, el tamaño va después de la posición y una barra: center / cover no-repeat. La declaración restablece las propiedades omitidas; un background posterior puede borrar una imagen o un color anterior. En fondos con varias capas, el color solo se escribe en la última capa del shorthand.

¿A qué se ancla durante el scroll?

scroll acompaña a la caja, pero no a su contenido al desplazarlo dentro. local se ancla al contenido desplazable. fixed toma el viewport como referencia; no crea position: fixed ni un parallax automático. Compara el scroll del documento y el de la preview y comprueba fixed en tus dispositivos de destino.

Fondo decorativo o imagen de contenido

La decisión depende del significado de la imagen, no de que visualmente llene una tarjeta.

Decoración prescindible

Usa background-image para una textura, un halo o una imagen que no añade información necesaria. El mensaje debe entenderse al quitarla. No existe un atributo alt para un fondo CSS; un rótulo visible o aria-label no convierte automáticamente la decoración en una imagen semántica.

Imagen con información

Usa <img> para una fotografía de producto, un diagrama o información visual relevante, con alt adecuado al contexto. Usa alt="" si el <img> es puramente decorativo. width y height reservan proporción; srcset/sizes o <picture> permiten adaptar el recurso. object-fit: cover puede producir el recorte visual sin perder la semántica HTML.

Texto, carga y preferencias

Comprueba el contraste sobre el resultado final y en todas sus posiciones responsivas; una imagen o un gradiente no garantiza legibilidad. Conserva un color base y, si hace falta, una superficie opaca para el texto. En colores forzados los gradientes se eliminan; los fondos basados en URL pueden permanecer. El contenido debe seguir siendo comprensible.

background-size cambia el tamaño pintado, no el peso descargado. Para recursos decorativos grandes, sirve una imagen optimizada; image-set() ofrece alternativas de resolución o formato que el navegador elige. Verifica esa función por separado y conserva una declaración url() anterior si necesitas cubrir navegadores que no la acepten.

Errores frecuentes

Comprueba la caja y la cascada antes de cambiar la imagen.

La imagen no se ve

Resultado esperado: Ver un fondo en una caja vacía.
Causa: La caja no tiene altura, la URL falla o una declaración posterior cambia el fondo.
Solución: Inspecciona dimensiones y CSS calculado; revisa la petición y conserva un color base.

Falta una parte importante

Resultado esperado: Llenar la caja y mostrar la imagen completa.
Causa: cover necesita recortar cuando las proporciones no coinciden.
Solución: Elige contain, cambia la proporción de la caja o ajusta la posición del punto de interés.

contain produce mosaicos

Resultado esperado: Ver una única imagen completa.
Causa: background-size no modifica el valor inicial repeat.
Solución: Añade background-repeat: no-repeat cuando quieras una sola copia.

El fondo desaparece al cambiar el color

Resultado esperado: Conservar la imagen y actualizar solo el color base.
Causa: background: <color> restablece background-image a none y las demás propiedades omitidas.
Solución: Cambia background-color o escribe el shorthand completo con todas las capas necesarias.

La información solo está en el fondo

Resultado esperado: Que todo el mundo reciba el mismo mensaje.
Causa: La decoración CSS no aporta una alternativa textual a las tecnologías de asistencia.
Solución: Pasa la información a HTML y usa <img> con alt si la imagen es contenido.

Soporte y compatibilidad

El soporte de background-image no certifica todos los valores que admite <image>.

La base de background-image, las capas múltiples y los ajustes clásicos tienen soporte consolidado. Los ejemplos ejecutan CSS nativo; verlos en este navegador no valida todos los motores ni los casos móviles.

Consulta las tablas del valor concreto para conic-gradient(), image-set(), espacios de interpolación de color o background-attachment: fixed. Funciones como cross-fade() o element() no heredan la disponibilidad general de la propiedad ni forman parte de estas recetas.

Una imagen que no carga no se sustituye por el color como otra imagen: deja visible lo pintado debajo. Mantén background-color, texto HTML y un diseño útil sin decoración; aplica @supports o declaraciones progresivas al introducir sintaxis con soporte distinto.