Docs ejecutables de CSS: Imagen de fondo

Q: ¿Cómo pongo una imagen de fondo en CSS?

Usa background-image: url("photo.jpg"); en el elemento. La ruta es relativa al archivo CSS (o a la página, en un atributo style o un elemento ). Dale un tamaño al elemento, porque un fondo nunca hace crecer a un elemento vacío.

Q: ¿Cómo hago que una imagen de fondo cubra todo el elemento?

Usa background-size: cover; con background-position: center;. La imagen escala hasta llenar la caja por completo, manteniendo sus proporciones, y lo que sobra se recorta.

Q: ¿Qué diferencia hay entre cover y contain?

cover llena toda la caja y recorta lo que no cabe. contain muestra la imagen entera y deja espacio vacío en dos lados cuando las proporciones son distintas.

Q: ¿Cómo evito que una imagen de fondo se repita?

Agrega background-repeat: no-repeat;. Por defecto una imagen de fondo se repite en las dos direcciones para llenar el elemento.

Q: ¿Por qué no se ve mi imagen de fondo?

Las causas habituales son una ruta incorrecta en url() (es relativa al archivo CSS), un elemento sin altura porque no tiene contenido, o una abreviatura background posterior que restableció la imagen.

Cómo poner una imagen de fondo

background-image pinta una imagen detrás del contenido, el padding y el borde del elemento. Por defecto empieza en la esquina superior izquierda de la caja de padding, mantiene su tamaño natural y se repite para llenar la caja:

<!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>

En un proyecto real, url() apunta a un archivo: url("images/hero.jpg"). La ruta es relativa a la hoja de estilo que la contiene (o a la página, en un elemento <style>). Los ejemplos de esta página usan pequeñas imágenes SVG escritas en línea como URLs data: para que funcionen en cualquier lugar.

Dos cosas que conviene saber desde el principio:

Un fondo no le da tamaño a un elemento. Un div vacío con una imagen de fondo mide 0px de alto. Dale contenido, padding, una height o un aspect-ratio.
Una imagen de fondo es decoración. Los lectores de pantalla la saltan y no tiene texto alternativo. Una imagen que transmite significado va en un elemento <img>.

background-size: cover, contain y longitudes

background-size escala la imagen. Las dos palabras clave mantienen sus proporciones:

<!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>

La imagen es el doble de ancha que de alta y cada caja es cuadrada.

Valor	Resultado
`auto` (por defecto)	El tamaño propio de la imagen
`cover`	Escala hasta llenar la caja por completo; lo que sobra se recorta
`contain`	Escala hasta que la imagen entera cabe; quedan franjas grises en dos lados
`200px`	200px de ancho, alto proporcional
`50% auto`	La mitad del ancho de la caja, alto proporcional
`100% 100%`	Exactamente el tamaño de la caja; deforma la imagen si las proporciones son distintas

cover es la opción habitual para banners principales y tarjetas. contain es para logos e ilustraciones que nunca deben recortarse.

background-position y background-repeat

background-position coloca la imagen dentro de la caja con palabras clave (top, center, bottom, left, right), porcentajes o longitudes. background-repeat controla la repetición. Prueba algunos valores:

<!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>

Prueba las posiciones top right, bottom 10px right 20px y 25% 75%, y los valores de repetición repeat-x, repeat-y, space (repeticiones con huecos para que ninguna quede cortada) y round (repeticiones redimensionadas para que quepa un número entero).

Capas: varios fondos y texto encima

background-image acepta una lista separada por comas. La primera capa se dibuja encima. El uso común es un degradado semitransparente sobre una foto, para que el texto blanco se siga leyendo:

<!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 le da altura a la caja vacía, y background-size: cover se aplica a las dos capas. Para más recetas de degradados, consulta degradados en CSS.

La abreviatura background

background define todas las propiedades de fondo en una línea. El tamaño debe ir justo después de la posición, separado por una barra, y el color va en la última capa:

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

El color de respaldo se ve mientras carga la imagen, y si falla. Cualquier propiedad que dejes fuera de la abreviatura se restablece a su valor por defecto, así que pon primero la abreviatura y después las propiedades individuales.

Otras propiedades de fondo

Propiedad	Qué hace
`background-attachment: fixed`	La imagen se queda fija mientras se desplaza la página (se ignora en Safari de iOS)
`background-origin`	Si la posición empieza en el borde, en el padding o en el contenido
`background-clip`	Dónde se pinta el fondo, incluido `text` para rellenar las letras
`background-blend-mode`	Mezcla las capas entre sí, como `multiply`

Errores comunes

Una ruta incorrecta. url() en una hoja de estilo es relativa al archivo CSS, no a la página HTML.
Un elemento vacío. No tiene altura, así que la imagen no tiene dónde verse.
Olvidar no-repeat con contain o con una imagen pequeña: se repite.
Estirar con 100% 100% cuando querías cover.
Imágenes importantes como fondos. Usa <img> con texto alternativo para el contenido; los fondos son invisibles para los lectores de pantalla.
Omitir las comillas alrededor de una URL data: que contiene espacios o comillas. Escribe siempre url("...").

Preguntas frecuentes

¿Cómo pongo una imagen de fondo en CSS?

Usa background-image: url("photo.jpg"); en el elemento. La ruta es relativa al archivo CSS (o a la página, en un atributo style o un elemento <style>). Dale un tamaño al elemento, porque un fondo nunca hace crecer a un elemento vacío.

¿Cómo hago que una imagen de fondo cubra todo el elemento?

Usa background-size: cover; con background-position: center;. La imagen escala hasta llenar la caja por completo, manteniendo sus proporciones, y lo que sobra se recorta.

¿Qué diferencia hay entre cover y contain?

cover llena toda la caja y recorta lo que no cabe. contain muestra la imagen entera y deja espacio vacío en dos lados cuando las proporciones son distintas.

¿Cómo evito que una imagen de fondo se repita?

Agrega background-repeat: no-repeat;. Por defecto una imagen de fondo se repite en las dos direcciones para llenar el elemento.

¿Por qué no se ve mi imagen de fondo?

Las causas habituales son una ruta incorrecta en url() (es relativa al archivo CSS), un elemento sin altura porque no tiene contenido, o una abreviatura background posterior que restableció la imagen.

Conceptos relacionados