background-image — Frontend Classroom

background-image es la propiedad que controla qué imagen o gradiente se pinta como fondo de un elemento. A diferencia de background-color, que produce un color sólido uniforme, background-image permite fondos complejos: fotografías, patrones repetitivos, degradados lineales y radiales, o incluso combinaciones de varias capas apiladas. Es la herramienta central para el acabado visual de secciones hero, banners y componentes decorativos.

La propiedad acepta dos tipos principales de valor: url() para referenciar un archivo de imagen externo, y funciones de gradiente que generan la imagen de forma programática en CSS, sin archivos externos. Los gradientes son especialmente poderosos porque permiten colores dinámicos que siguen la paleta sin depender de assets.

El comportamiento por defecto cuando se aplica una imagen de fondo es que se repite en mosaico para cubrir todo el elemento. En la práctica casi siempre se combina con background-repeat, background-size y background-position para controlar ese comportamiento — o se usa el shorthand background que los agrupa. Ver la entrada de background para el detalle completo de esas sub-propiedades.

Cómo funciona

background-image se pinta encima de background-color pero debajo del contenido del elemento. Si la imagen no cubre toda el área (por background-size o por ser más pequeña que el elemento), se repite por defecto. La imagen no ocupa espacio en el layout — es puramente visual.

Cuando se usa url(), el navegador hace una petición HTTP para cargar el archivo. Si la imagen no carga, el fondo cae en background-color. Cuando se usan funciones de gradiente, no hay petición — el degradado se genera en CSS, lo que los hace ideales para el sandbox de ejercicios.

Sintaxis

/* Imagen de archivo */
.hero { background-image: url('portada.jpg'); }
.hero { background-image: url('data:image/svg+xml,...'); } /* data URI */

/* Gradiente lineal */
.banner { background-image: linear-gradient(to right, #1e3a5f, #3a7bd5); }

/* Gradiente radial */
.avatar { background-image: radial-gradient(circle, #667eea, #764ba2); }

/* Sin imagen (reset) */
.sin-imagen { background-image: none; }

Hero con linear-gradient(135deg, #1e3a5f, #3a7bd5)

Panel con radial-gradient()

Valores

`url()` — imagen de archivo

Referencia un archivo de imagen (JPG, PNG, WebP, SVG, etc.) por URL o data URI. La URL puede ser relativa al archivo CSS o absoluta.

.hero        { background-image: url('/img/portada.jpg'); }
.patron      { background-image: url('/img/patron.png'); }

Data URI: para imágenes pequeñas o íconos SVG, se puede embeber la imagen directamente en el CSS con una data URI. Esto evita una petición HTTP adicional y es la forma correcta de usar imágenes en el sandbox de este sitio (cicatriz A.0.5 de docs/CICATRICES.md — el sandbox no carga URLs externas):

.icono {
  background-image: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><circle cx="12" cy="12" r="10" fill="%230d9488"/></svg>');
}

`linear-gradient()` — degradado lineal

Genera un degradado entre dos o más colores a lo largo de una línea. Es la función de gradiente más usada.

Sintaxis básica:

/* keyword de dirección */
background-image: linear-gradient(to right, #1e3a5f, #3a7bd5);
background-image: linear-gradient(to bottom, #667eea, #764ba2);

/* ángulo en grados */
background-image: linear-gradient(45deg, #1e3a5f, #3a7bd5);
background-image: linear-gradient(180deg, #1e3a5f, #3a7bd5); /* = to bottom */

Sin dirección explícita, el default es to bottom (equivalente a 180deg).

Con paradas de color (color stops):

background-image: linear-gradient(
  to right,
  #1e3a5f 0%,    /* color en el 0% del recorrido */
  #3a7bd5 60%,   /* color en el 60% */
  #7ec8e3 100%   /* color final */
);

Las paradas permiten controlar dónde ocurren las transiciones: podés tener un degradado que cambia rápido al principio y despacio al final, o que tiene una franja de color sólido en el medio.

/* Franja de color sólido en el centro */
background-image: linear-gradient(
  to right,
  #1e3a5f 30%,
  #1e3a5f 70%,   /* mismo color → sin transición */
  #3a7bd5 100%
);

`radial-gradient()` — degradado radial

Se expande desde un punto central hacia afuera en forma circular o elíptica.

/* Círculo desde el centro */
background-image: radial-gradient(circle, #667eea, #1e3a5f);

/* Elipse (default) desde el centro */
background-image: radial-gradient(#f9a8d4, #c026d3);

/* Desde una posición específica */
background-image: radial-gradient(circle at top left, #f9a8d4, transparent);
background-image: radial-gradient(circle at 30% 70%, #667eea, #1e3a5f);

El keyword circle fuerza una forma circular; sin él, la forma se ajusta al tamaño del elemento (elipse). La posición después de at indica el centro del gradiente.

Apilado de imágenes

background-image acepta múltiples valores separados por coma. Las imágenes se apilan: la primera en la lista queda encima, la última debajo.

.hero {
  background-image:
    linear-gradient(rgba(0, 0, 0, 0.4), rgba(0, 0, 0, 0.4)),  /* overlay oscuro */
    url('foto.jpg');                                            /* foto debajo */
}

Este patrón es muy común para hacer legible el texto sobre una fotografía: se aplica un overlay semitransparente encima de la imagen.

/* Dos gradientes apilados */
.fondo {
  background-image:
    radial-gradient(circle at top right, rgba(102, 126, 234, 0.3), transparent 60%),
    linear-gradient(to bottom, #0f172a, #1e293b);
}

`none` (valor inicial)

Sin imagen de fondo. Es el valor inicial de cualquier elemento.

Cuándo usarlo

Situación	Valor recomendado
Hero o banner con degradado	`linear-gradient()`
Avatar con efecto de luz	`radial-gradient()`
Fotografía de fondo	`url()` + `background-size: cover`
Overlay sobre foto	gradiente semitransparente + `url()`
Sandbox o ejercicios (sin recursos externos)	`linear-gradient()` o data URI

Notas, gotchas e interacción

La imagen se repite por defecto. El valor inicial de background-repeat es repeat, por lo que una imagen más pequeña que el elemento se repite en mosaico. Casi siempre se combina con background-repeat: no-repeat y background-size: cover o contain.
background-image no carga recursos externos en el sandbox de este sitio. El sandbox ejecuta el código en un <iframe> aislado. Para practicar con imágenes de fondo, usá linear-gradient(), radial-gradient() o data URIs (cicatriz A.0.5 de docs/CICATRICES.md).
El fallback de color. Cuando background-image falla o no carga, el usuario ve background-color. Siempre es buena práctica declarar un color de fondo compatible cuando se usan fotografías como fondo.
Gradientes no heredados. Como toda propiedad de background, background-image no se hereda. Cada elemento necesita su propia declaración.
background-image: none resetea la imagen sin tocar el color. Si usás el shorthand background para resetear, también resetea background-color. Si solo querés quitar la imagen, usá la longhand.
Accesibilidad: las imágenes de fondo son decorativas para los lectores de pantalla — no tienen equivalente de alt. Si la imagen transmite información que el usuario necesita, usá un elemento <img> con alt, no background-image.

Vigente / legacy

background-image con url() existe desde CSS1. Las funciones linear-gradient() y radial-gradient() son CSS3 (Baseline widely). La sintaxis sin prefijos es la estándar; los prefijos -webkit-linear-gradient() y similares fueron necesarios circa 2011-2013 pero hoy son legacy.

conic-gradient() es una adición más reciente (Baseline newly, 2023) para degradados cónicos — no entra en el temario de este curso pero está disponible en todos los navegadores modernos.