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 calculado nativo
• 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 lazy 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 la configuración del loader.

Cuando se usa una URL externa, debe agregarla 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 a medida que cambia el tamaño del viewport.

• Demo del layout intrinsic (predeterminado)
  • Con intrinsic, la imagen escalará las dimensiones hacia abajo para viewports más pequeños, pero mantendrá las dimensiones originales para viewports más 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 más pequeños y hacia arriba para viewports más grandes.
  • Asegúrese de que el elemento padre use display: block en su hoja de estilos.
• Demo del layout fill
  • Con fill, la imagen se estirará tanto en ancho como en alto a las dimensiones del elemento padre, siempre que el elemento padre sea relativo.
  • Esto generalmente 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 utilizada 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 el ancho de 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 tiene dos propósitos importantes relacionados con el rendimiento de la imagen:

Primero, el valor de sizes es utilizado 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 es del mismo tamaño o más grande que el viewport. La propiedad sizes le permite indicar al navegador que la imagen será realmente más pequeña que el ancho completo de la pantalla. Si no especifica un valor de sizes, se usará un valor predeterminado de 100vw (ancho completo de la pantalla).

Segundo, el valor de sizes se analiza y se utiliza 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 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 tabletas y un diseño de 3 columnas en escritorios, debe 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 33vw en sizes, 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 true, la imagen se considerará de alta prioridad y se precargará. La carga lazy 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 priority, 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 completará 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 placeholder blur
• Demo del efecto shimmer 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 de 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 placeholder.

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 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 correctamente. 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 placeholders puede afectar el rendimiento de su aplicación.

Pruébelo:

• Demo de la prop blurDataURL predeterminada
• Demo del efecto shimmer 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 utilizado para detectar la intersección del viewport con la imagen y activar la carga lazy. 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 del componente <Image /> se pasarán al elemento img subyacente, con excepción de las siguientes:

• srcSet. Utilice 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/**',
      },
    ],
  },
}

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

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

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

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

Dominios

Advertencia: Recomendamos configurar remotePatterns estrictos en lugar de domains para proteger su aplicación de usuarios maliciosos. Solo use domains si es 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 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 cargador (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/',
  },
}

Cargadores integrados

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

• Por defecto: Funciona automáticamente con next dev, next start o un servidor personalizado
• Vercel: Funciona automáticamente al desplegar en Vercel, sin configuración necesaria. Más información
• Imgix: loader: 'imgix'
• Cloudinary: loader: 'cloudinary'
• Akamai: loader: 'akamai'
• Personalizado: loader: 'custom' usa 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 cargador diferente al predeterminado. Más información en la discusión.

El cargador 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 compatibles con 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'],
  },
}

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 del caché

Lo siguiente describe el algoritmo de caché para el cargador predeterminado. Para todos los demás cargadores, 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 el caché con la nueva fecha de expiración.

El estado del caché de una imagen se puede determinar 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 el caché (ocurre como máximo una vez, en la primera visita)
• STALE - la ruta está en el caché pero excedió el tiempo de revalidación, por lo que se actualizará en segundo plano
• HIT - la ruta está en el 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 del 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 imágenes generadas posibles.
• 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 generará automáticamente un hash del contenido 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 del 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 el caché en este momento, por lo que es mejor mantener minimumCacheTTL bajo. De lo contrario, puede que necesite 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 que desee 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 estáticas de imágenes en su next.config.js:

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

Permitir SVG peligrosamente

El cargador 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 cabeceras adecuadas de Content Security Policy (CSP).

Si necesita servir imágenes SVG con la API de Optimización de Imágenes predeterminada, puede configurar dangerouslyAllowSVG en su next.config.js:

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

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.

Imágenes animadas

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

La detección automática de 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