Image Component

Core Idea

<Image> (next/image) estende <img> com otimização automática: redimensionamento, mudança de formato (WebP/AVIF), lazy loading e prevenção de layout shift. Configuração via props no componente e via images em next.config.js para políticas globais (padrões de URL permitidos, tamanhos, cache).

Key Concepts

src: path interno, URL externa absoluta (requer remotePatterns), ou import estático (hash automático + blurDataURL automático para jpg/png/webp/avif não animado).
width/height: tamanho intrínseco em pixels, usado só para calcular aspect ratio (não controla o tamanho renderizado, isso é CSS); obrigatório exceto com import estático ou fill.
fill: expande a imagem ao tamanho do elemento pai; pai precisa position: relative/fixed/absolute; combine com objectFit: "contain"|"cover".
sizes: usado com fill ou layout responsivo via CSS; sem ele o browser assume 100vw e baixa imagem maior que o necessário; com ele o Next.js gera srcset completo (640w, 750w...) em vez de limitado (1x, 2x).
quality: inteiro 1-100 (default 75); valores fora da allowlist qualities de next.config.js são arredondados para o mais próximo permitido.
preload: substitui priority (deprecated no Next.js 16); usar true só na imagem LCP/above-the-fold; senão preferir loading="eager"/fetchPriority="high".
placeholder: empty (default), blur (requer blurDataURL), ou data:image/....
unoptimized: desliga otimização (útil para SVG, GIF animado, imagens <1KB); pode ser setado globalmente via images.unoptimized no config.
loader/loaderFile: função custom (por instância ou global) que recebe {src, width, quality} e retorna a URL da imagem otimizada.
overrideSrc: mantém o src original no atributo <img> (SEO) enquanto ainda gera srcset otimizado.

Code Examples

import Image from 'next/image'

export default function Page() {
  return (
    <Image
      src="/profile.png"
      width={500}
      height={500}
      alt="Picture of the author"
    />
  )
}

O que demonstra: uso básico com width/height explícitos para reservar espaço e evitar layout shift.

<Image
  fill
  src="/example.png"
  sizes="(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 33vw"
/>

O que demonstra: layout responsivo com fill + sizes, gerando srcset completo para diferentes breakpoints.

module.exports = {
  images: {
    remotePatterns: [
      { protocol: 'https', hostname: '**.example.com', pathname: '/account123/**', search: '' },
    ],
    formats: ['image/avif', 'image/webp'],
    qualities: [25, 50, 75, 100],
  },
}

O que demonstra: allowlist de origem remota com wildcard, formatos preferidos (AVIF > WebP como fallback) e allowlist de qualidades permitidas (obrigatória a partir do Next.js 16).

Reference Tables

Config option	Default	Propósito
`deviceSizes`	`[640, 750, 828, 1080, 1200, 1920, 2048, 3840]`	breakpoints de largura de device
`imageSizes`	`[32, 48, 64, 96, 128, 256, 384]`	larguras extras para imagens menores que a tela, concatenadas com `deviceSizes`
`qualities`	`[75]`	allowlist de qualidade (obrigatória desde v16)
`formats`	`['image/webp']`	formatos de saída, ordem importa (primeiro match do header `Accept` vence)
`minimumCacheTTL`	`14400` (4h)	TTL do cache de imagem otimizada; usa o maior entre esse valor e o `Cache-Control` da origem
`path`	`/_next/image`	prefixo da Image Optimization API
`disableStaticImages`	`false`	desliga import estático de imagem
`maximumRedirects`	`3`	redirects HTTP seguidos ao buscar imagem remota
`maximumDiskCacheSize`	50% do disco disponível	tamanho máx. do cache em disco, LRU quando excede
`maximumResponseBody`	`50_000_000` (50MB)	tamanho máx. da imagem de origem buscada
`dangerouslyAllowLocalIP`	`false`	permite otimizar imagens de IP local (risco SSRF)

Anti-patterns

Usar remotePatterns sem search: '' explícito: omitir search implica wildcard **, permitindo query strings arbitrárias, use um valor específico como search: '?v=2'.
Usar style para largura customizada sem height: 'auto': quebra o aspect ratio da imagem.
onLoad/onError/onLoadingComplete em Server Component: essas props aceitam função e exigem Client Component para serializar.
priority em Next.js 16: deprecated, use preload.
onLoadingComplete: deprecated desde v14, use onLoad.
src remoto que requer auth com loader default: a Image Optimization API não repassa headers por segurança; use unoptimized nesses casos.
minimumCacheTTL alto sem mecanismo de invalidação: não há invalidação automática, é preciso trocar o src manualmente ou apagar <distDir>/cache/images.

Key Takeaways

width/height (ou fill) sempre definem aspect ratio, nunca o tamanho renderizado, isso é CSS.
sizes é obrigatório com fill/layout responsivo para evitar baixar a imagem no tamanho máximo (100vw) por padrão.
A partir do Next.js 16, qualities no config é obrigatório restringir, senão qualquer valor de quality seria aceito na API pública.
remotePatterns com wildcard mal configurado é vetor de abuso (otimizar URLs arbitrárias); sempre restrinja protocol/hostname/pathname/search.
AVIF comprime ~20% menor que WebP mas leva ~50% mais tempo pra codificar; usar os dois juntos dobra o storage de cache.

Connects To

Components (ch105): índice dos componentes built-in.
Font (ch106): outro componente de otimização automática (fontes vs. imagens).