Image

El componente Image de Next.js extiende el elemento HTML <img> para la optimización automática de imágenes.

import Image from 'next/image'

export default function Page() {
  return (
    <Image
      src="/profile.png"
      width={500}
      height={500}
      alt="Foto del autor"
    />
  )
}

Referencia

Props

Las siguientes props están disponibles:

src

La fuente de la imagen. Puede ser una de las siguientes:

Una ruta interna como string.

<Image src="/profile.png" />

Una URL externa absoluta (debe estar configurada con remotePatterns).

<Image src="https://example.com/profile.png" />

Una importación estática.

import profile from './profile.png'

export default function Page() {
  return <Image src={profile} />
}

alt

La propiedad alt se utiliza para describir la imagen para lectores de pantalla y motores de búsqueda. También es el texto de respaldo si las imágenes están deshabilitadas o ocurre un error al cargar la imagen.

Debe contener texto que pueda reemplazar la imagen sin cambiar el significado de la página. No está destinado a complementar la imagen y no debe repetir información que ya se proporcione en los subtítulos arriba o abajo de la imagen.

Si la imagen es puramente decorativa o no está destinada al usuario, la propiedad alt debe ser un string vacío (alt="").

Aprende más sobre pautas de accesibilidad de imágenes.

width y height

Las propiedades width y height representan el tamaño intrínseco de la imagen en píxeles. Esta propiedad se utiliza para inferir la proporción de aspecto correcta utilizada por los navegadores para reservar espacio para la imagen y evitar cambios de diseño durante la carga. No determina el tamaño renderizado de la imagen, que se controla mediante CSS.

<Image src="/profile.png" width={500} height={500} />

Debes establecer ambas propiedades width y height a menos que:

• La imagen sea importada estáticamente
• La imagen tenga la propiedad fill

Si no se conocen la altura y el ancho, recomendamos usar la propiedad fill.

fill

Un booleano que hace que la imagen se expanda al tamaño del elemento padre.

<Image src="/profile.png" fill={true} />

Posicionamiento:

• El elemento padre debe asignar position: "relative", "fixed", "absolute".
• Por defecto, el elemento <img> usa position: "absolute".

Ajuste del objeto:

Si no se aplican estilos a la imagen, esta se estirará para ajustarse al contenedor. Puedes usar objectFit para controlar el recorte y la escala.

• "contain": La imagen se reducirá para ajustarse al contenedor y preservar la proporción de aspecto.
• "cover": La imagen llenará el contenedor y será recortada.

Aprende más sobre position y object-fit.

loader

Una función personalizada utilizada para generar la URL de la imagen. La función recibe los siguientes parámetros y devuelve un string de URL para la imagen:

• src
• width
• quality

'use client'

import Image from 'next/image'

const imageLoader = ({ src, width, quality }) => {
  return `https://example.com/${src}?w=${width}&q=${quality || 75}`
}

export default function Page() {
  return (
    <Image
      loader={imageLoader}
      src="me.png"
      alt="Foto del autor"
      width={500}
      height={500}
    />
  )
}

Es bueno saberlo: Usar props como onLoad, que aceptan una función, requiere usar Componentes de Cliente para serializar la función proporcionada.

Alternativamente, puedes usar la configuración loaderFile en next.config.js para configurar cada instancia de next/image en tu aplicación, sin pasar una prop.

sizes

Define los tamaños de la imagen en diferentes puntos de interrupción. Utilizado por el navegador para elegir el tamaño más apropiado del srcset generado.

import Image from 'next/image'

export default function Page() {
  return (
    <div className="grid-element">
      <Image
        fill
        src="/example.png"
        sizes="(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 33vw"
      />
    </div>
  )
}

sizes debe usarse cuando:

• La imagen usa la propiedad fill
• Se usa CSS para hacer la imagen responsiva

Si falta sizes, el navegador asume que la imagen será tan ancha como la ventana gráfica (100vw). Esto puede hacer que se descarguen imágenes innecesariamente grandes.

Además, sizes afecta cómo se genera srcset:

• Sin sizes: Next.js genera un srcset limitado (ej. 1x, 2x), adecuado para imágenes de tamaño fijo.
• Con sizes: Next.js genera un srcset completo (ej. 640w, 750w, etc.), optimizado para diseños responsivos.

Aprende más sobre srcset y sizes en web.dev y mdn.

quality

Un entero entre 1 y 100 que establece la calidad de la imagen optimizada. Valores más altos aumentan el tamaño del archivo y la fidelidad visual. Valores más bajos reducen el tamaño del archivo pero pueden afectar la nitidez.

// La calidad por defecto es 75
<Image quality={75} />

Si has configurado qualities en next.config.js, el valor debe coincidir con una de las entradas permitidas.

Es bueno saberlo: Si la imagen original ya es de baja calidad, establecer un valor de calidad alto aumentará el tamaño del archivo sin mejorar la apariencia.

style

Permite pasar estilos CSS al elemento de imagen subyacente.

const imageStyle = {
  borderRadius: '50%',
  border: '1px solid #fff',
  width: '100px',
  height: 'auto',
}

export default function ProfileImage() {
  return <Image src="..." style={imageStyle} />
}

Es bueno saberlo: Si usas la prop style para establecer un ancho personalizado, asegúrate de también establecer height: 'auto' para preservar la proporción de aspecto de la imagen.

priority

Un booleano que indica si la imagen debe ser precargada.

// La prioridad por defecto es false
<Image priority={false} />

• true: Precarga la imagen. Desactiva la carga diferida.
• false: Carga la imagen de forma diferida.

Cuándo usarlo:

• La imagen está arriba del pliegue.
• La imagen es el elemento Largest Contentful Paint (LCP).
• Quieres mejorar el rendimiento de carga inicial de tu página.

Cuándo no usarlo:

• Cuando se usa la prop loading (generará advertencias).

loading

Controla cuándo debe comenzar a cargarse la imagen.

// Por defecto es lazy
<Image loading="lazy" />

• lazy: Diferir la carga de la imagen hasta que alcance una distancia calculada desde la ventana gráfica.
• eager: Cargar la imagen inmediatamente, independientemente de su posición en la página.

Usa eager solo cuando quieras asegurarte de que la imagen se cargue inmediatamente.

Aprende más sobre el atributo loading.

placeholder

Especifica un marcador de posición para usar mientras se carga la imagen, mejorando el rendimiento de carga percibido.

// Por defecto es empty
<Image placeholder="empty" />

• empty: Sin marcador de posición mientras se carga la imagen.
• blur: Usa una versión difuminada de la imagen como marcador de posición. Debe usarse con la propiedad blurDataURL.
• data:image/...: Usa la URL de datos como marcador de posición.

Ejemplos:

• Marcador de posición blur
• Efecto de brillo con prop placeholder de URL de datos
• Efecto de color con prop blurDataURL

Aprende más sobre el atributo placeholder.

blurDataURL

Una URL de datos para usar como imagen de marcador de posición antes de que la imagen se cargue correctamente. Puede configurarse automáticamente o usarse con la propiedad placeholder="blur".

<Image placeholder="blur" blurDataURL="..." />

La imagen se amplía y difumina automáticamente, por lo que se recomienda una imagen muy pequeña (10px o menos).

Automático

Si src es una importación estática de un archivo jpg, png, webp o avif, blurDataURL se agrega automáticamente, a menos que la imagen esté animada.

Configuración manual

Si la imagen es dinámica o remota, debes proporcionar blurDataURL tú mismo. Para generar una, puedes usar:

• Una herramienta en línea como png-pixel.com
• Una biblioteca como Plaiceholder

Una blurDataURL grande puede afectar el rendimiento. Mantenla pequeña y simple.

Ejemplos:

• Prop blurDataURL por defecto
• Efecto de color con prop blurDataURL

onLoad

Una función de callback que se invoca una vez que la imagen se carga completamente y se ha eliminado el marcador de posición.

<Image onLoad={(e) => console.log(e.target.naturalWidth)} />

La función de callback se llamará con un argumento, el evento que tiene un target que referencia el elemento <img> subyacente.

Es bueno saberlo: Usar props como onLoad, que aceptan una función, requiere usar Componentes de Cliente para serializar la función proporcionada.

onError

Una función de callback que se invoca si la imagen no se carga.

<Image onError={(e) => console.error(e.target.id)} />

Es bueno saberlo: Usar props como onError, que aceptan una función, requiere usar Componentes de Cliente para serializar la función proporcionada.

unoptimized

Un booleano que indica si la imagen debe optimizarse. Esto es útil para imágenes que no se benefician de la optimización, como imágenes pequeñas (menos de 1KB), imágenes vectoriales (SVG) o imágenes animadas (GIF).

import Image from 'next/image'

const UnoptimizedImage = (props) => {
  // Por defecto es false
  return <Image {...props} unoptimized />
}

• true: La imagen fuente se servirá tal cual desde src en lugar de cambiar calidad, tamaño o formato.
• false: La imagen fuente se optimizará.

Desde Next.js 12.3.0, esta prop puede asignarse a todas las imágenes actualizando next.config.js con la siguiente configuración:

module.exports = {
  images: {
    unoptimized: true,
  },
}

overrideSrc

Cuando se proporciona la prop src al componente <Image>, tanto el atributo srcset como src se generan automáticamente para el <img> resultante.

<Image src="/profile.jpg" />

<img
  srcset="
    /_next/image?url=%2Fme.jpg&w=640&q=75 1x,
    /_next/image?url=%2Fme.jpg&w=828&q=75 2x
  "
  src="/_next/image?url=%2Fme.jpg&w=828&q=75"
/>

En algunos casos, no es deseable que se genere el atributo src y es posible que desees anularlo usando la prop overrideSrc.

Por ejemplo, al actualizar un sitio web existente de <img> a <Image>, es posible que desees mantener el mismo atributo src para fines de SEO, como clasificación de imágenes o evitar un nuevo rastreo.

<Image src="/profile.jpg" overrideSrc="/override.jpg" />

<img
  srcset="
    /_next/image?url=%2Fme.jpg&w=640&q=75 1x,
    /_next/image?url=%2Fme.jpg&w=828&q=75 2x
  "
  src="/override.jpg"
/>

decoding

Una sugerencia al navegador que indica si debe esperar a que la imagen se decodifique antes de presentar otras actualizaciones de contenido o no.

// Por defecto es async
<Image decoding="async" />

• async: Decodifica la imagen de forma asíncrona y permite que otros contenidos se rendericen antes de que se complete.
• sync: Decodifica la imagen de forma síncrona para una presentación atómica con otros contenidos.
• auto: Sin preferencia. El navegador elige el mejor enfoque.

Aprende más sobre el atributo decoding.

Otras Props

Otras propiedades en el componente <Image /> se pasarán al elemento img subyacente con la excepción de las siguientes:

• srcSet: Usa Device Sizes en su lugar.

Props obsoletas

onLoadingComplete

Advertencia: Obsoleto en Next.js 14, utiliza onLoad en su lugar.

Una función de callback que se invoca una vez que la imagen se ha cargado completamente y el placeholder ha sido eliminado.

La función de callback se llamará con un argumento, una referencia al elemento <img> subyacente.

'use client'

<Image onLoadingComplete={(img) => console.log(img.naturalWidth)} />

Bueno saber: Usar props como onLoadingComplete, que aceptan una función, requiere usar Client Components para serializar la función proporcionada.

Opciones de configuración

Puedes configurar el Componente Image en next.config.js. Las siguientes opciones están disponibles:

localPatterns

Usa localPatterns en tu archivo next.config.js para permitir que imágenes de rutas locales específicas sean optimizadas y bloquear todas las demás.

module.exports = {
  images: {
    localPatterns: [
      {
        pathname: '/assets/images/**',
        search: '',
      },
    ],
  },
}

El ejemplo anterior asegurará que la propiedad src de next/image debe comenzar con /assets/images/ y no debe tener una cadena de consulta. Intentar optimizar cualquier otra ruta responderá con un error 400 Bad Request.

remotePatterns

Usa remotePatterns en tu archivo next.config.js para permitir imágenes de rutas externas específicas y bloquear todas las demás. Esto asegura que solo se sirvan imágenes externas de tu cuenta.

module.exports = {
  images: {
    remotePatterns: [new URL('https://example.com/account123/**')],
  },
}

Si usas una versión anterior a 15.3.0, puedes configurar remotePatterns usando el objeto:

module.exports = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'example.com',
        port: '',
        pathname: '/account123/**',
        search: '',
      },
    ],
  },
}

El ejemplo anterior asegurará que la propiedad src de next/image debe comenzar con https://example.com/account123/ y no debe tener una cadena de consulta. Cualquier otro protocolo, hostname, puerto o ruta no coincidente responderá con un error 400 Bad Request.

Patrones Wildcard:

Los patrones wildcard pueden usarse tanto para pathname como para hostname y tienen la siguiente sintaxis:

• * coincide con un solo segmento de ruta o subdominio
• ** coincide con cualquier número de segmentos de ruta al final o subdominios al principio. Esta sintaxis no funciona en medio del patrón.

module.exports = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: '**.example.com',
        port: '',
        search: '',
      },
    ],
  },
}

Esto permite subdominios como image.example.com. Las cadenas de consulta y puertos personalizados siguen bloqueados.

Bueno saber: Cuando omites protocol, port, pathname o search, entonces se implica el wildcard **. Esto no se recomienda porque puede permitir que actores maliciosos optimicen URLs que no tenías intención de permitir.

Cadenas de consulta:

También puedes restringir cadenas de consulta usando la propiedad search:

module.exports = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'assets.example.com',
        search: '?v=1727111025337',
      },
    ],
  },
}

El ejemplo anterior asegurará que la propiedad src de next/image debe comenzar con https://assets.example.com y debe tener exactamente la cadena de consulta ?v=1727111025337. Cualquier otro protocolo o cadena de consulta responderá con un error 400 Bad Request.

loaderFile

loaderFiles te permite usar un servicio personalizado de optimización de imágenes en lugar de Next.js.

module.exports = {
  images: {
    loader: 'custom',
    loaderFile: './my/image/loader.js',
  },
}

La ruta debe ser relativa a la raíz del proyecto. El archivo debe exportar una función por defecto que devuelva una cadena de URL:

'use client'

export default function myImageLoader({ src, width, quality }) {
  return `https://example.com/${src}?w=${width}&q=${quality || 75}`
}

Ejemplo:

• Configuración de Cargador de Imágenes Personalizado

Alternativamente, puedes usar la prop loader para configurar cada instancia de next/image.

deviceSizes

deviceSizes te permite especificar una lista de puntos de interrupción de ancho de dispositivo. Estos anchos se usan cuando el componente next/image usa la prop sizes para asegurar que se sirva la imagen correcta para el dispositivo del usuario.

Si no se proporciona configuración, se usa el siguiente valor por defecto:

module.exports = {
  images: {
    deviceSizes: [640, 750, 828, 1080, 1200, 1920, 2048, 3840],
  },
}

imageSizes

imageSizes te permite especificar una lista de anchos de imagen. Estos anchos se concatenan con el array de device sizes para formar el array completo de tamaños usados para generar el srcset de la imagen.

Si no se proporciona configuración, se usa el siguiente valor por defecto:

module.exports = {
  images: {
    imageSizes: [16, 32, 48, 64, 96, 128, 256, 384],
  },
}

imageSizes solo se usa para imágenes que proporcionan una prop sizes, lo que indica que la imagen es menor que el ancho completo de la pantalla. Por lo tanto, los tamaños en imageSizes deben ser todos menores que el tamaño más pequeño en deviceSizes.

qualities

qualities te permite especificar una lista de valores de calidad de imagen.

module.exports = {
  images: {
    qualities: [25, 50, 75],
  },
}

En el ejemplo anterior, solo se permiten tres calidades: 25, 50 y 75. Si la prop quality no coincide con un valor en este array, la imagen fallará con un error 400 Bad Request.

formats

formats te permite especificar una lista de formatos de imagen a usar.

module.exports = {
  images: {
    // Valor por defecto
    formats: ['image/webp'],
  },
}

Next.js detecta automáticamente los formatos de imagen soportados por el navegador a través de la cabecera Accept de la solicitud para determinar el mejor formato de salida.

Si la cabecera Accept coincide con más de uno de los formatos configurados, se usa la primera coincidencia en el array. Por lo tanto, el orden del array importa. Si no hay coincidencia (o la imagen fuente está animada), se usará el formato original de la imagen.

Puedes habilitar soporte para AVIF, que volverá al formato original de la imagen src si el navegador no soporta AVIF:

module.exports = {
  images: {
    formats: ['image/avif'],
  },
}

Bueno saber:

• Todavía recomendamos usar WebP para la mayoría de los casos de uso.
• AVIF generalmente tarda un 50% más en codificarse pero comprime un 20% más pequeño comparado con WebP. Esto significa que la primera vez que se solicita una imagen, normalmente será más lenta, pero las solicitudes posteriores que están en caché serán más rápidas.
• Si autoalojas con un Proxy/CDN delante de Next.js, debes configurar el Proxy para reenviar la cabecera Accept.

minimumCacheTTL

minimumCacheTTL te permite configurar el Time to Live (TTL) en segundos para imágenes optimizadas en caché. En muchos casos, es mejor usar una Static Image Import que automáticamente hashear el contenido del archivo y cachear la imagen para siempre con una cabecera Cache-Control de immutable.

Si no se proporciona configuración, se usa el siguiente valor por defecto.

module.exports = {
  images: {
    minimumCacheTTL: 60, // 1 minuto
  },
}

Puedes aumentar el TTL para reducir el número de revalidaciones y potencialmente reducir costos:

module.exports = {
  images: {
    minimumCacheTTL: 2678400, // 31 días
  },
}

La expiración (o más bien Max Age) de la imagen optimizada se define por el minimumCacheTTL o la cabecera Cache-Control de la imagen upstream, lo que sea mayor.

Si necesitas cambiar el comportamiento de caché por imagen, puedes configurar headers para establecer la cabecera Cache-Control en la imagen upstream (ej. /some-asset.jpg, no en /_next/image mismo).

No hay un mecanismo para invalidar la caché en este momento, así que es mejor mantener minimumCacheTTL bajo. De lo contrario, puede que necesites cambiar manualmente la prop src o eliminar el archivo en caché <distDir>/cache/images.

disableStaticImages

disableStaticImages te permite desactivar las importaciones de imágenes estáticas.

El comportamiento por defecto te permite importar archivos estáticos como import icon from './icon.png' y luego pasar eso a la propiedad src. En algunos casos, puede que desees desactivar esta característica si entra en conflicto con otros plugins que esperan que la importación se comporte de manera diferente.

Puedes desactivar las importaciones de imágenes estáticas dentro de tu next.config.js:

module.exports = {
  images: {
    disableStaticImages: true,
  },
}

dangerouslyAllowSVG

dangerouslyAllowSVG te permite servir imágenes SVG.

module.exports = {
  images: {
    dangerouslyAllowSVG: true,
  },
}

Por defecto, Next.js no optimiza imágenes SVG por algunas razones:

• SVG es un formato vectorial, lo que significa que puede redimensionarse sin pérdida.
• SVG tiene muchas de las mismas características que HTML/CSS, lo que puede llevar a vulnerabilidades sin las cabeceras adecuadas de Content Security Policy (CSP).

Recomendamos usar la prop unoptimized cuando la prop src se sabe que es SVG. Esto sucede automáticamente cuando src termina con ".svg".

<Image src="/my-image.svg" unoptimized />

Además, se recomienda encarecidamente configurar también contentDispositionType para forzar al navegador a descargar la imagen, así como contentSecurityPolicy para evitar que los scripts incrustados en la imagen se ejecuten.

module.exports = {
  images: {
    dangerouslyAllowSVG: true,
    contentDispositionType: 'attachment',
    contentSecurityPolicy: "default-src 'self'; script-src 'none'; sandbox;",
  },
}

contentDispositionType

contentDispositionType te permite configurar la cabecera Content-Disposition.

module.exports = {
  images: {
    contentDispositionType: 'inline',
  },
}

Por defecto, el loader establece la cabecera Content-Disposition en attachment para mayor protección ya que la API puede servir imágenes remotas arbitrarias.

El valor por defecto es attachment que fuerza al navegador a descargar la imagen al visitarla directamente. Esto es particularmente importante cuando dangerouslyAllowSVG es true.

Opcionalmente puedes configurar inline para permitir que el navegador renderice la imagen al visitarla directamente, sin descargarla.

Opciones de configuración obsoletas

domains

Advertencia: Obsoleto desde Next.js 14 en favor de remotePatterns estrictos para proteger tu aplicación de usuarios maliciosos. Solo usa domains si eres dueño de todo el contenido servido desde el dominio.

Similar a remotePatterns, la configuración domains puede usarse para proporcionar una lista de hostnames permitidos para imágenes externas. Sin embargo, la configuración domains no soporta coincidencia de patrones wildcard y no puede restringir protocolo, puerto o pathname.

A continuación se muestra un ejemplo de la propiedad domains en el archivo next.config.js:

module.exports = {
  images: {
    domains: ['assets.acme.com'],
  },
}

Funciones

getImageProps

La función getImageProps puede usarse para obtener las props que se pasarían al elemento <img> subyacente, y en su lugar pasarlas a otro componente, estilo, canvas, etc.

import { getImageProps } from 'next/image'

const props = getImageProps({
  src: 'https://example.com/image.jpg',
  alt: 'Una vista panorámica de montañas',
  width: 1200,
  height: 800,
})

function ImageWithCaption() {
  return (
    <figure>
      <img {...props} />
      <figcaption>Una vista panorámica de montañas</figcaption>
    </figure>
  )
}

Esto también evita llamar a useState() de React, lo que puede llevar a un mejor rendimiento, pero no puede usarse con la prop placeholder porque el placeholder nunca se eliminará.

Errores conocidos del navegador

El componente next/image usa lazy loading nativo del navegador, que puede volver a eager loading para navegadores más antiguos antes de Safari 15.4. Cuando se usa el placeholder blur-up, navegadores más antiguos antes de Safari 12 volverán a un placeholder vacío. Cuando se usan estilos con width/height de auto, es posible causar Layout Shift en navegadores más antiguos antes de Safari 15 que no preservan la relación de aspecto. Para más detalles, ver este video de MDN.

• Safari 15 - 16.3 muestra un borde gris mientras carga. Safari 16.4 solucionó este problema. Posibles soluciones:

  • Usar CSS @supports (font: -apple-system-body) and (-webkit-appearance: none) { img[loading="lazy"] { clip-path: inset(0.6px) } }
  • Usar priority si la imagen está above the fold

• Firefox 67+ muestra un fondo blanco mientras carga. Posibles soluciones:

  • Habilitar formats AVIF
  • Usar placeholder

Ejemplos

Estilizando imágenes

Estilizar el componente Image es similar a estilizar un elemento <img> normal, pero hay algunas pautas a tener en cuenta:

Usa className o style, no styled-jsx. En la mayoría de los casos, recomendamos usar la prop className. Esto puede ser un CSS Module importado, una hoja de estilos global, etc.

import styles from './styles.module.css'

export default function MyImage() {
  return <Image className={styles.image} src="/my-image.png" alt="Mi Imagen" />
}

También puedes usar la prop style para asignar estilos en línea.

export default function MyImage() {
  return (
    <Image style={{ borderRadius: '8px' }} src="/my-image.png" alt="Mi Imagen" />
  )
}

Cuando uses fill, el elemento padre debe tener position: relative o display: block. Esto es necesario para el renderizado correcto del elemento de imagen en ese modo de diseño.

<div style={{ position: 'relative' }}>
  <Image fill src="/my-image.png" alt="Mi Imagen" />
</div>

No puedes usar styled-jsx porque está limitado al componente actual (a menos que marques el estilo como global).

Imágenes responsivas con una exportación estática

Cuando importas una imagen estática, Next.js establece automáticamente su ancho y alto basándose en el archivo. Puedes hacer que la imagen sea responsiva configurando el estilo:

import Image from 'next/image'
import mountains from '../public/mountains.jpg'

export default function Responsive() {
  return (
    <div style={{ display: 'flex', flexDirection: 'column' }}>
      <Image
        alt="Mountains"
        // Importar una imagen establecerá
        // automáticamente el ancho y alto
        src={mountains}
        sizes="100vw"
        // Hacer que la imagen se muestre a todo el ancho
        // y preservar su relación de aspecto
        style={{
          width: '100%',
          height: 'auto',
        }}
      />
    </div>
  )
}

Imágenes responsivas con una URL remota

Si la imagen de origen es una URL dinámica o remota, debes proporcionar las propiedades width y height para que Next.js pueda calcular la relación de aspecto:

import Image from 'next/image'

export default function Page({ photoUrl }) {
  return (
    <Image
      src={photoUrl}
      alt="Foto del autor"
      sizes="100vw"
      style={{
        width: '100%',
        height: 'auto',
      }}
      width={500}
      height={300}
    />
  )
}

Pruébalo:

• Demostración de imagen responsiva al viewport

Imagen responsiva con fill

Si no conoces la relación de aspecto de la imagen, puedes añadir la propiedad fill con la propiedad objectFit configurada como cover. Esto hará que la imagen llene todo el ancho de su contenedor padre.

import Image from 'next/image'
import mountains from '../public/mountains.jpg'

export default function Fill() {
  return (
    <div
      style={{
        display: 'grid',
        gridGap: '8px',
        gridTemplateColumns: 'repeat(auto-fit, minmax(400px, auto))',
      }}
    >
      <div style={{ position: 'relative', width: '400px' }}>
        <Image
          alt="Mountains"
          src={mountains}
          fill
          sizes="(min-width: 808px) 50vw, 100vw"
          style={{
            objectFit: 'cover', // cover, contain, none
          }}
        />
      </div>
      {/* Y más imágenes en la cuadrícula... */}
    </div>
  )
}

Imagen de fondo

Usa la propiedad fill para que la imagen cubra toda el área de la pantalla:

import Image from 'next/image'
import mountains from '../public/mountains.jpg'

export default function Background() {
  return (
    <Image
      alt="Mountains"
      src={mountains}
      placeholder="blur"
      quality={100}
      fill
      sizes="100vw"
      style={{
        objectFit: 'cover',
      }}
    />
  )
}

Para ejemplos del componente Image usado con varios estilos, consulta la Demostración del Componente Image.

Imágenes remotas

Para usar una imagen remota, la propiedad src debe ser una cadena URL.

import Image from 'next/image'

export default function Page() {
  return (
    <Image
      src="https://s3.amazonaws.com/my-bucket/profile.png"
      alt="Foto del autor"
      width={500}
      height={500}
    />
  )
}

Dado que Next.js no tiene acceso a archivos remotos durante el proceso de construcción, deberás proporcionar manualmente las propiedades width, height y opcionalmente blurDataURL.

Los atributos width y height se usan para inferir la relación de aspecto correcta de la imagen y evitar cambios de diseño al cargar la imagen. El width y height no determinan el tamaño renderizado del archivo de imagen.

Para permitir de forma segura la optimización de imágenes, define una lista de patrones de URL soportados en next.config.js. Sé lo más específico posible para evitar usos maliciosos. Por ejemplo, la siguiente configuración solo permitirá imágenes de un bucket específico de AWS S3:

module.exports = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 's3.amazonaws.com',
        port: '',
        pathname: '/my-bucket/**',
        search: '',
      },
    ],
  },
}

Detección de tema

Si deseas mostrar una imagen diferente para modo claro y oscuro, puedes crear un nuevo componente que envuelva dos componentes <Image> y muestre el correcto basado en una consulta CSS de medios.

.imgDark {
  display: none;
}

@media (prefers-color-scheme: dark) {
  .imgLight {
    display: none;
  }
  .imgDark {
    display: unset;
  }
}

import styles from './theme-image.module.css'
import Image, { ImageProps } from 'next/image'

type Props = Omit<ImageProps, 'src' | 'priority' | 'loading'> & {
  srcLight: string
  srcDark: string
}

const ThemeImage = (props: Props) => {
  const { srcLight, srcDark, ...rest } = props

  return (
    <>
      <Image {...rest} src={srcLight} className={styles.imgLight} />
      <Image {...rest} src={srcDark} className={styles.imgDark} />
    </>
  )
}

Nota importante: El comportamiento predeterminado de loading="lazy" asegura que solo se cargue la imagen correcta. No puedes usar priority o loading="eager" porque eso haría que ambas imágenes se carguen. En su lugar, puedes usar fetchPriority="high".

Pruébalo:

• Demostración de detección de tema claro/oscuro

Dirección de arte

Si deseas mostrar una imagen diferente para móvil y escritorio, a veces llamado Dirección de Arte, puedes proporcionar diferentes propiedades src, width, height y quality a getImageProps().

import { getImageProps } from 'next/image'

export default function Home() {
  const common = { alt: 'Ejemplo de Dirección de Arte', sizes: '100vw' }
  const {
    props: { srcSet: desktop },
  } = getImageProps({
    ...common,
    width: 1440,
    height: 875,
    quality: 80,
    src: '/desktop.jpg',
  })
  const {
    props: { srcSet: mobile, ...rest },
  } = getImageProps({
    ...common,
    width: 750,
    height: 1334,
    quality: 70,
    src: '/mobile.jpg',
  })

  return (
    <picture>
      <source media="(min-width: 1000px)" srcSet={desktop} />
      <source media="(min-width: 500px)" srcSet={mobile} />
      <img {...rest} style={{ width: '100%', height: 'auto' }} />
    </picture>
  )
}

Fondo CSS

Incluso puedes convertir la cadena srcSet a la función CSS image-set() para optimizar una imagen de fondo.

import { getImageProps } from 'next/image'

function getBackgroundImage(srcSet = '') {
  const imageSet = srcSet
    .split(', ')
    .map((str) => {
      const [url, dpi] = str.split(' ')
      return `url("${url}") ${dpi}`
    })
    .join(', ')
  return `image-set(${imageSet})`
}

export default function Home() {
  const {
    props: { srcSet },
  } = getImageProps({ alt: '', width: 128, height: 128, src: '/img.png' })
  const backgroundImage = getBackgroundImage(srcSet)
  const style = { height: '100vh', width: '100vw', backgroundImage }

  return (
    <main style={style}>
      <h1>Hola Mundo</h1>
    </main>
  )
}

Historial de Versiones