Componente <Image> (Legacy)

A partir de Next.js 13, el componente next/image fue reescrito para mejorar tanto el rendimiento como la experiencia del desarrollador. Para proporcionar una solución de actualización compatible con versiones anteriores, el antiguo next/image fue renombrado a next/legacy/image.

Consulte la nueva Referencia de API de next/image

Comparación

En comparación con next/legacy/image, el nuevo componente next/image tiene los siguientes cambios:

• Elimina el envoltorio <span> alrededor de <img> en favor del aspect ratio nativo calculado
• Añade soporte para la prop style canónica
  • Elimina la prop layout en favor de style o className
  • Elimina la prop objectFit en favor de style o className
  • Elimina la prop objectPosition en favor de style o className
• Elimina la implementación de IntersectionObserver en favor de carga diferida nativa
  • Elimina la prop lazyBoundary ya que no hay equivalente nativo
  • Elimina la prop lazyRoot ya que no hay equivalente nativo
• Elimina la configuración loader en favor de la prop loader
• Cambia la prop alt de opcional a requerida
• Cambia el callback onLoadingComplete para recibir referencia al elemento <img>

Props Requeridas

El componente <Image /> requiere las siguientes propiedades.

src

Debe ser uno de los siguientes:

• Un archivo de imagen importado estáticamente
• Una cadena de ruta. Puede ser una URL externa absoluta o una ruta interna dependiendo de la prop loader o configuración del loader.

Cuando se usa una URL externa, debe añadirla a remotePatterns en next.config.js.

width

La propiedad width puede representar el ancho renderizado o el ancho original en píxeles, dependiendo de las propiedades layout y sizes.

Cuando se usa layout="intrinsic" o layout="fixed", la propiedad width representa el ancho renderizado en píxeles, por lo que afectará el tamaño de la imagen.

Cuando se usa layout="responsive" o layout="fill", la propiedad width representa el ancho original en píxeles, por lo que solo afectará la relación de aspecto.

La propiedad width es requerida, excepto para imágenes importadas estáticamente, o aquellas con layout="fill".

height

La propiedad height puede representar la altura renderizada o la altura original en píxeles, dependiendo de las propiedades layout y sizes.

Cuando se usa layout="intrinsic" o layout="fixed", la propiedad height representa la altura renderizada en píxeles, por lo que afectará el tamaño de la imagen.

Cuando se usa layout="responsive" o layout="fill", la propiedad height representa la altura original en píxeles, por lo que solo afectará la relación de aspecto.

La propiedad height es requerida, excepto para imágenes importadas estáticamente, o aquellas con layout="fill".

Props Opcionales

El componente <Image /> acepta varias propiedades adicionales más allá de las requeridas. Esta sección describe las propiedades más comúnmente usadas del componente Image. Encuentre detalles sobre propiedades menos usadas en la sección Props Avanzadas.

layout

El comportamiento de diseño de la imagen cuando cambia el tamaño del viewport.

• Demo del layout intrinsic (predeterminado)
  • Con intrinsic, la imagen escalará las dimensiones hacia abajo para viewports pequeños, pero mantendrá las dimensiones originales para viewports grandes.
• Demo del layout fixed
  • Con fixed, las dimensiones de la imagen no cambiarán con el viewport (sin capacidad de respuesta) similar al elemento img nativo.
• Demo del layout responsive
  • Con responsive, la imagen escalará las dimensiones hacia abajo para viewports pequeños y hacia arriba para viewports grandes.
  • Asegúrese de que el elemento padre use display: block en su hoja de estilos.
• Demo del layout fill
  • Con fill, la imagen estirará tanto el ancho como el alto a las dimensiones del elemento padre, siempre que el elemento padre sea relativo.
  • Esto usualmente se combina con la propiedad objectFit.
  • Asegúrese de que el elemento padre tenga position: relative en su hoja de estilos.
• Demo de imagen de fondo

loader

Una función personalizada usada para resolver URLs. Establecer el loader como prop en el componente Image anula el loader predeterminado definido en la sección images de next.config.js.

Un loader es una función que devuelve una cadena URL para la imagen, dados los siguientes parámetros:

• src
• width
• quality

Aquí hay un ejemplo de uso de un loader personalizado:

import Image from 'next/legacy/image'

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

const MyImage = (props) => {
  return (
    <Image
      loader={myLoader}
      src="me.png"
      alt="Picture of the author"
      width={500}
      height={500}
    />
  )
}

sizes

Una cadena que proporciona información sobre qué tan ancha será la imagen en diferentes breakpoints. El valor de sizes afectará significativamente el rendimiento para imágenes que usan layout="responsive" o layout="fill". Será ignorado para imágenes que usan layout="intrinsic" o layout="fixed".

La propiedad sizes sirve para dos propósitos importantes relacionados con el rendimiento de la imagen:

Primero, el valor de sizes es usado por el navegador para determinar qué tamaño de imagen descargar, del conjunto de fuentes generado automáticamente por next/legacy/image. Cuando el navegador elige, aún no conoce el tamaño de la imagen en la página, por lo que selecciona una imagen que tenga el mismo tamaño o más grande que el viewport. La propiedad sizes le permite indicar al navegador que la imagen será en realidad más pequeña que el ancho completo de la pantalla. Si no especifica un valor para sizes, se usará un valor predeterminado de 100vw (ancho completo de la pantalla).

Segundo, el valor de sizes se analiza y se usa para recortar los valores en el conjunto de fuentes creado automáticamente. Si la propiedad sizes incluye tamaños como 50vw, que representan un porcentaje del ancho del viewport, entonces el conjunto de fuentes se recorta para no incluir valores que sean demasiado pequeños como para ser necesarios.

Por ejemplo, si sabe que su estilo hará que una imagen tenga el ancho completo en dispositivos móviles, un diseño de 2 columnas en tablets y un diseño de 3 columnas en escritorios, debería incluir una propiedad sizes como la siguiente:

import Image from 'next/legacy/image'
const Example = () => (
  <div className="grid-element">
    <Image
      src="/example.png"
      layout="fill"
      sizes="(max-width: 768px) 100vw,
              (max-width: 1200px) 50vw,
              33vw"
    />
  </div>
)

Este ejemplo de sizes podría tener un efecto dramático en las métricas de rendimiento. Sin el tamaño 33vw, la imagen seleccionada del servidor sería 3 veces más ancha de lo necesario. Debido a que el tamaño del archivo es proporcional al cuadrado del ancho, sin sizes el usuario descargaría una imagen que es 9 veces más grande de lo necesario.

Aprenda más sobre srcset y sizes:

• web.dev
• mdn

quality

La calidad de la imagen optimizada, un entero entre 1 y 100 donde 100 es la mejor calidad. Por defecto es 75.

priority

Cuando es verdadero, la imagen se considerará de alta prioridad y se precargará. La carga diferida se desactiva automáticamente para imágenes que usan priority.

Debe usar la propiedad priority en cualquier imagen detectada como el elemento Largest Contentful Paint (LCP). Puede ser apropiado tener múltiples imágenes con prioridad, ya que diferentes imágenes pueden ser el elemento LCP para diferentes tamaños de viewport.

Solo debe usarse cuando la imagen es visible sin hacer scroll. Por defecto es false.

placeholder

Un marcador de posición para usar mientras la imagen se carga. Los valores posibles son blur o empty. Por defecto es empty.

Cuando es blur, se usará la propiedad blurDataURL como marcador de posición. Si src es un objeto de una importación estática y la imagen importada es .jpg, .png, .webp, o .avif, entonces blurDataURL se llenará automáticamente.

Para imágenes dinámicas, debe proporcionar la propiedad blurDataURL. Soluciones como Plaiceholder pueden ayudar con la generación de base64.

Cuando es empty, no habrá marcador de posición mientras la imagen se carga, solo espacio vacío.

Pruébelo:

• Demo del marcador de posición blur
• Demo del efecto brillante con prop blurDataURL
• Demo del efecto de color con prop blurDataURL

Props Avanzadas

En algunos casos, puede necesitar un uso más avanzado. El componente <Image /> acepta opcionalmente las siguientes propiedades avanzadas.

style

Permite pasar estilos CSS al elemento de imagen subyacente.

Tenga en cuenta que todos los modos layout aplican sus propios estilos al elemento de imagen, y estos estilos automáticos tienen prioridad sobre la prop style.

También tenga en cuenta que las props requeridas width y height pueden interactuar con su estilo. Si usa estilos para modificar el width de una imagen, debe establecer también el estilo height="auto", o su imagen se distorsionará.

objectFit

Define cómo la imagen se ajustará a su contenedor padre cuando se usa layout="fill".

Este valor se pasa a la propiedad CSS object-fit para la imagen src.

objectPosition

Define cómo se posiciona la imagen dentro de su elemento padre cuando se usa layout="fill".

Este valor se pasa a la propiedad CSS object-position aplicada a la imagen.

onLoadingComplete

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

La función onLoadingComplete acepta un parámetro, un objeto con las siguientes propiedades:

• naturalWidth
• naturalHeight

loading

Atención: Esta propiedad está destinada solo para uso avanzado. Cambiar una imagen para cargar con eager normalmente dañará el rendimiento.

Recomendamos usar la propiedad priority en su lugar, que carga la imagen de forma eager correctamente para casi todos los casos de uso.

El comportamiento de carga de la imagen. Por defecto es lazy.

Cuando es lazy, difiere la carga de la imagen hasta que alcanza una distancia calculada desde el viewport.

Cuando es eager, carga la imagen inmediatamente.

Aprenda más

blurDataURL

Una Data URL para usar como imagen de marcador de posición antes de que la imagen src se cargue exitosamente. Solo tiene efecto cuando se combina con placeholder="blur".

Debe ser una imagen codificada en base64. Se ampliará y difuminará, por lo que se recomienda una imagen muy pequeña (10px o menos). Incluir imágenes más grandes como marcadores de posición puede dañar el rendimiento de su aplicación.

Pruébelo:

• Demo de la prop blurDataURL predeterminada
• Demo del efecto brillante con prop blurDataURL
• Demo del efecto de color con prop blurDataURL

También puede generar una Data URL de color sólido para que coincida con la imagen.

lazyBoundary

Una cadena (con sintaxis similar a la propiedad margin) que actúa como el cuadro delimitador usado para detectar la intersección del viewport con la imagen y activar la carga diferida. Por defecto es "200px".

Si la imagen está anidada en un elemento padre desplazable que no es el documento raíz, también deberá asignar la prop lazyRoot.

Aprenda más

lazyRoot

Una Ref de React que apunta al elemento padre desplazable. Por defecto es null (el viewport del documento).

La Ref debe apuntar a un elemento DOM o a un componente React que reenvíe la Ref al elemento DOM subyacente.

Ejemplo apuntando a un elemento DOM

import Image from 'next/legacy/image'
import React from 'react'

const Example = () => {
  const lazyRoot = React.useRef(null)

  return (
    <div ref={lazyRoot} style={{ overflowX: 'scroll', width: '500px' }}>
      <Image lazyRoot={lazyRoot} src="/one.jpg" width="500" height="500" />
      <Image lazyRoot={lazyRoot} src="/two.jpg" width="500" height="500" />
    </div>
  )
}

Ejemplo apuntando a un componente React

import Image from 'next/legacy/image'
import React from 'react'

const Container = React.forwardRef((props, ref) => {
  return (
    <div ref={ref} style={{ overflowX: 'scroll', width: '500px' }}>
      {props.children}
    </div>
  )
})

const Example = () => {
  const lazyRoot = React.useRef(null)

  return (
    <Container ref={lazyRoot}>
      <Image lazyRoot={lazyRoot} src="/one.jpg" width="500" height="500" />
      <Image lazyRoot={lazyRoot} src="/two.jpg" width="500" height="500" />
    </Container>
  )
}

Aprenda más

unoptimized

Cuando es true, la imagen fuente se servirá tal cual sin cambiar calidad, tamaño o formato. Por defecto es false.

import Image from 'next/image'

const UnoptimizedImage = (props) => {
  return <Image {...props} unoptimized />
}

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

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

Otras propiedades

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

• srcSet. Use Tamaños de dispositivo en su lugar.
• ref. Use onLoadingComplete en su lugar.
• decoding. Siempre es "async".

Opciones de configuración

Patrones remotos

Para proteger su aplicación de usuarios maliciosos, se requiere configuración para usar imágenes externas. Esto asegura que solo imágenes externas de su cuenta puedan servirse desde la API de Optimización de Imágenes de Next.js. Estas imágenes externas pueden configurarse con la propiedad remotePatterns en su archivo next.config.js, como se muestra a continuación:

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

Nota importante: El ejemplo anterior asegurará que la propiedad src de next/legacy/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 400 Bad Request.

A continuación un ejemplo de la propiedad remotePatterns en el archivo next.config.js usando un patrón comodín en el hostname:

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

Nota importante: El ejemplo anterior asegurará que la propiedad src de next/legacy/image debe comenzar con https://img1.example.com o https://me.avatar.example.com o cualquier número de subdominios. No puede tener un puerto o cadena de consulta. Cualquier otro protocolo o hostname no coincidente responderá con 400 Bad Request.

Los patrones comodín 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

La sintaxis ** no funciona en medio del patrón.

Nota importante: Al omitir protocol, port, pathname o search entonces se implica el comodín **. Esto no se recomienda porque puede permitir que actores maliciosos optimicen URLs que no pretendía.

A continuación un ejemplo de la propiedad remotePatterns en el archivo next.config.js usando search:

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

Nota importante: El ejemplo anterior asegurará que la propiedad src de next/legacy/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 400 Bad Request.

Dominios

Advertencia: Obsoleto desde Next.js 14 en favor de remotePatterns estrictos para proteger su aplicación de usuarios maliciosos. Solo use domains si posee 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 admite coincidencia de patrones comodín y no puede restringir protocolo, puerto o ruta.

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

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

Configuración del Loader

Si desea usar un proveedor en la nube para optimizar imágenes en lugar de usar la API de Optimización de Imágenes integrada de Next.js, puede configurar el loader y el prefijo path en su archivo next.config.js. Esto le permite usar URLs relativas para el src de Image y generar automáticamente la URL absoluta correcta para su proveedor.

module.exports = {
  images: {
    loader: 'imgix',
    path: 'https://example.com/myaccount/',
  },
}

Loaders integrados

Los siguientes proveedores de optimización de imágenes están incluidos:

• Predeterminado: Funciona automáticamente con next dev, next start o un servidor personalizado
• Vercel: Funciona automáticamente al desplegar en Vercel, no se requiere configuración. Más información
• Imgix: loader: 'imgix'
• Cloudinary: loader: 'cloudinary'
• Akamai: loader: 'akamai'
• Personalizado: loader: 'custom' use un proveedor en la nube personalizado implementando la propiedad loader en el componente next/legacy/image

Si necesita un proveedor diferente, puede usar la propiedad loader con next/legacy/image.

Las imágenes no pueden optimizarse en tiempo de compilación usando output: 'export', solo bajo demanda. Para usar next/legacy/image con output: 'export', necesitará usar un loader diferente al predeterminado. Más información en la discusión.

El loader predeterminado del componente next/legacy/image usa squoosh porque es rápido de instalar y adecuado para un entorno de desarrollo. Al usar next start en su entorno de producción, se recomienda encarecidamente instalar sharp ejecutando npm i sharp en el directorio de su proyecto. Esto no es necesario para despliegues en Vercel, ya que sharp se instala automáticamente.

Avanzado

La siguiente configuración es para casos de uso avanzados y generalmente no es necesaria. Si elige configurar las propiedades a continuación, anulará cualquier cambio a los valores predeterminados de Next.js en futuras actualizaciones.

Tamaños de dispositivo

Si conoce los anchos de dispositivo esperados de sus usuarios, puede especificar una lista de puntos de interrupción de ancho de dispositivo usando la propiedad deviceSizes en next.config.js. Estos anchos se usan cuando el componente next/legacy/image usa layout="responsive" o layout="fill" para asegurar que se sirva la imagen correcta para el dispositivo del usuario.

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

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

Tamaños de imagen

Puede especificar una lista de anchos de imagen usando la propiedad images.imageSizes en su archivo next.config.js. Estos anchos se concatenan con el array de tamaños de dispositivo para formar el array completo de tamaños usados para generar los srcset de imagen.

La razón por la que hay dos listas separadas es que imageSizes solo se usa para imágenes que proporcionan una propiedad 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.

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

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

Formatos aceptables

La API de Optimización de Imágenes predeterminada detectará automáticamente los formatos de imagen admitidos por el navegador a través de la cabecera Accept de la solicitud.

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 es animada), la API de Optimización de Imágenes recurrirá al formato original de la imagen.

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

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

Puede habilitar soporte para AVIF con la siguiente configuración.

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

Nota importante: AVIF generalmente tarda un 20% más en codificarse pero se comprime un 20% más pequeño en comparación con WebP. Esto significa que la primera vez que se solicita una imagen, generalmente será más lento y luego las solicitudes posteriores que están en caché serán más rápidas.

Comportamiento de caché

Lo siguiente describe el algoritmo de caché para el loader predeterminado. Para todos los demás loaders, consulte la documentación de su proveedor en la nube.

Las imágenes se optimizan dinámicamente al solicitarse y se almacenan en el directorio <distDir>/cache/images. El archivo de imagen optimizado se servirá para solicitudes posteriores hasta que se alcance la expiración. Cuando se realiza una solicitud que coincide con un archivo en caché pero expirado, la imagen expirada se sirve inmediatamente como obsoleta. Luego la imagen se optimiza nuevamente en segundo plano (también llamado revalidación) y se guarda en la caché con la nueva fecha de expiración.

El estado de caché de una imagen puede determinarse leyendo el valor de la cabecera de respuesta x-nextjs-cache (x-vercel-cache cuando se despliega en Vercel). Los valores posibles son los siguientes:

• MISS - la ruta no está en la caché (ocurre como máximo una vez, en la primera visita)
• STALE - la ruta está en la caché pero excedió el tiempo de revalidación, por lo que se actualizará en segundo plano
• HIT - la ruta está en la caché y no ha excedido el tiempo de revalidación

La expiración (o más bien Max Age) se define por la configuración minimumCacheTTL o la cabecera Cache-Control de la imagen upstream, la que sea mayor. Específicamente, se usa el valor max-age de la cabecera Cache-Control. Si se encuentran tanto s-maxage como max-age, se prefiere s-maxage. El max-age también se transmite a cualquier cliente downstream incluyendo CDNs y navegadores.

• Puede configurar minimumCacheTTL para aumentar la duración de la caché cuando la imagen upstream no incluye cabecera Cache-Control o el valor es muy bajo.
• Puede configurar deviceSizes y imageSizes para reducir el número total de posibles imágenes generadas.
• Puede configurar formatos para deshabilitar múltiples formatos en favor de un solo formato de imagen.

Tiempo mínimo de caché (TTL)

Puede configurar el Time to Live (TTL) en segundos para imágenes optimizadas en caché. En muchos casos, es mejor usar una Importación de Imagen Estática que automáticamente hashear los contenidos del archivo y almacenar la imagen para siempre con una cabecera Cache-Control de immutable.

module.exports = {
  images: {
    minimumCacheTTL: 60,
  },
}

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, la que sea mayor.

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

No hay mecanismo para invalidar la caché en este momento, por lo que es mejor mantener minimumCacheTTL bajo. De lo contrario, puede necesitar cambiar manualmente la propiedad src o eliminar <distDir>/cache/images.

Deshabilitar importaciones estáticas

El comportamiento predeterminado le permite importar archivos estáticos como import icon from './icon.png' y luego pasarlo a la propiedad src.

En algunos casos, puede desear deshabilitar esta función si entra en conflicto con otros plugins que esperan que la importación se comporte de manera diferente.

Puede deshabilitar las importaciones de imágenes estáticas dentro de su next.config.js:

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

Permitir SVG peligrosamente

El loader predeterminado no optimiza imágenes SVG por varias razones. Primero, SVG es un formato vectorial lo que significa que puede redimensionarse sin pérdida. Segundo, SVG tiene muchas de las mismas características que HTML/CSS, lo que puede llevar a vulnerabilidades sin las adecuadas cabeceras de Content Security Policy (CSP).

Por lo tanto, recomendamos usar la propiedad unoptimized cuando se sabe que la propiedad src es SVG. Esto sucede automáticamente cuando src termina en ".svg".

Sin embargo, si necesita servir imágenes SVG con la API de Optimización de Imágenes predeterminada, puede establecer dangerouslyAllowSVG dentro de su next.config.js:

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

Además, se recomienda encarecidamente establecer 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.

Imágenes animadas

El loader predeterminado omitirá automáticamente la Optimización de Imágenes para imágenes animadas y servirá la imagen tal cual.

La auto-detección para archivos animados es de mejor esfuerzo y admite GIF, APNG y WebP. Si desea omitir explícitamente la Optimización de Imágenes para una imagen animada dada, use la propiedad unoptimized.

Historial de versiones