Image

Core Idea

next/image estende <img> com otimização automática (redimensionamento, formato moderno, lazy loading, prevenção de layout shift) via uma API de otimização própria, configurável tanto por props do componente quanto por opções globais em next.config.js.

Key Concepts

src: path interno, URL externa absoluta (exige remotePatterns) ou import estático (import img from './x.png').
width/height: tamanho intrínseco em pixels, usado só para calcular aspect ratio (evita layout shift); não controla o tamanho renderizado (isso é CSS). Obrigatórios exceto com import estático ou fill.
fill: expande a imagem ao tamanho do elemento pai, que precisa de position: relative/fixed/absolute; combine com objectFit: 'contain'|'cover'.
sizes: informa ao browser o tamanho renderizado em cada breakpoint; obrigatório com fill ou layout responsivo via CSS — sem ele, o browser assume 100vw e pode baixar imagens maiores que o necessário; também muda como o srcset é gerado (limitado 1x/2x sem sizes, completo por largura com sizes).
quality: inteiro 1-100 (default 75); valores fora do allowlist qualities (config) são arredondados para o mais próximo.
loader: função ({src, width, quality}) => url para gerar URL customizada de otimização; alternativa global é loaderFile no config.
preload: substitui priority (deprecated na v16) — insere <link> de preload no <head>; usar para a imagem LCP/hero, não para múltiplas imagens candidatas a LCP.
loading: 'lazy' (default) ou 'eager'.
placeholder: 'empty' (default), 'blur' (requer blurDataURL) ou uma Data URL direta.
blurDataURL: gerado automaticamente para imports estáticos de jpg/png/webp/avif não animados; manual para imagens dinâmicas/remotas.
unoptimized: pula a otimização (útil para SVG, GIF animado, imagens <1KB); pode ser ligado globalmente via config.
overrideSrc: força o atributo src final do <img> gerado (ex. manter URL antiga por SEO ao migrar de <img> para <Image>).
decoding: 'async' (default), 'sync' ou 'auto'.
getImageProps: função que retorna as props que iriam para o <img> subjacente, para repassar a outro elemento (picture, canvas); não pode usar placeholder (nunca seria removido).
remotePatterns: allowlist obrigatória em next.config.js para otimizar imagens externas — usa protocol, hostname, port, pathname, search; suporta wildcards * (um segmento) e ** (múltiplos segmentos, só no início/fim).
localPatterns: allowlist de paths locais permitidos para otimização.
qualities: allowlist de qualidades permitidas (default [75]); obrigatório configurar explicitamente desde a v16 por segurança.

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 mínimo com width/height obrigatórios.

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

<Image loader={imageLoader} src="me.png" alt="..." width={500} height={500} />

O que demonstra: loader customizado por instância, alternativa ao loaderFile global.

<div style={{ position: 'relative' }}>
  <Image fill src="/my-image.png" alt="My Image" sizes="(min-width: 808px) 50vw, 100vw" />
</div>

O que demonstra: fill exige container posicionado e sizes para srcset responsivo correto.

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

O que demonstra: allowlist obrigatória de origem externa; qualquer outro protocolo/host/path/query recebe 400 Bad Request.

import { getImageProps } from 'next/image'

const { props } = getImageProps({ src: 'https://example.com/image.jpg', alt: 'A scenic mountain view', width: 1200, height: 800 })

function ImageWithCaption() {
  return (
    <figure>
      <img {...props} />
      <figcaption>A scenic mountain view</figcaption>
    </figure>
  )
}

O que demonstra: getImageProps repassando props otimizadas para um <img> fora do componente <Image>.

Reference Tables

Props do componente `<Image>`

Prop	Tipo / Default	Descrição
`src`	string / StaticImport	path interno, URL externa (com `remotePatterns`) ou import estático
`alt`	string, obrigatório	texto alternativo; string vazia para imagem puramente decorativa
`width` / `height`	number	tamanho intrínseco em px; dispensável com import estático ou `fill`
`fill`	boolean	expande ao tamanho do pai posicionado
`loader`	função	gera URL customizada de otimização
`sizes`	string	tamanhos por breakpoint, controla geração do `srcset`
`quality`	1-100, default 75	qualidade da imagem otimizada
`style`	objeto CSS	estilos inline no elemento
`preload`	boolean, default false	insere `<link>` de preload no `<head>` (substitui `priority`, deprecated na v16)
`loading`	`'lazy'` (default) \| `'eager'`	quando a imagem começa a carregar
`placeholder`	`'empty'` (default) \| `'blur'` \| data URL	placeholder durante carregamento
`blurDataURL`	string	Data URL para o placeholder blur
`onLoad`	função	callback ao completar carregamento
`onError`	função	callback em falha de carregamento
`unoptimized`	boolean, default false	serve a imagem sem otimização
`overrideSrc`	string	sobrescreve o atributo `src` final gerado
`decoding`	`'async'` (default) \| `'sync'` \| `'auto'`	hint de decodificação ao browser
`onLoadingComplete`	função (deprecated v14)	usar `onLoad`

Opções de `next.config.js` → `images`

Opção	Default	Descrição
`localPatterns`	-	allowlist de paths locais otimizáveis
`remotePatterns`	-	allowlist de origens externas (protocol/hostname/port/pathname/search)
`loaderFile`	-	função loader customizada global
`path`	`/_next/image`	prefixo da Image Optimization API
`deviceSizes`	`[640,750,828,1080,1200,1920,2048,3840]`	breakpoints de dispositivo
`imageSizes`	`[32,48,64,96,128,256,384]`	larguras extras p/ imagens menores que a tela inteira
`qualities`	`[75]` (obrigatório configurar na v16)	allowlist de qualidades permitidas
`formats`	`['image/webp']`	formatos de saída, ordem = prioridade
`minimumCacheTTL`	`14400` (4h)	TTL do cache de imagens otimizadas, em segundos
`disableStaticImages`	`false`	desabilita import estático de imagens
`maximumRedirects`	`3`	redirects seguidos ao buscar imagem remota
`maximumDiskCacheSize`	50% do disco livre (checado 1x no startup)	tamanho máx. do cache em disco, bytes
`maximumResponseBody`	`50_000_000` (50MB)	tamanho máx. da imagem-fonte buscada
`dangerouslyAllowLocalIP`	`false`	permite otimizar imagens de IP local (risco de SSRF)
`dangerouslyAllowSVG`	`false`	permite otimizar SVG (risco de XSS sem CSP)
`contentDispositionType`	`'attachment'`	header `Content-Disposition`
`contentSecurityPolicy`	-	header CSP aplicado às imagens servidas
`domains` (deprecated v14)	-	usar `remotePatterns`

Anti-patterns

Usar fill sem position: relative/fixed/absolute no pai: a imagem não se posiciona corretamente (usa position: absolute internamente).
Omitir sizes com fill ou CSS responsivo: browser assume 100vw, baixando imagens desnecessariamente grandes.
dangerouslyAllowSVG: true sem contentSecurityPolicy + contentDispositionType: 'attachment': abre risco de script embutido em SVG malicioso.
remotePatterns sem protocol/port/pathname/search explícitos: wildcard ** implícito é permissivo demais para produção.
Aumentar minimumCacheTTL sem plano de invalidação: não existe invalidação de cache nativa — mudar o src ou apagar <distDir>/cache/images manualmente é o único jeito.
Usar preload/loading="eager" junto de fetchPriority: redundante, escolher só um mecanismo de priorização.
Duas imagens com preload ou loading="eager" simultâneas (ex. theme light/dark): força carregar ambas; usar fetchPriority="high" em vez disso nesse cenário.

Key Takeaways

priority foi deprecated na v16 em favor de preload, que é mais explícito sobre a intenção (inserir <link> no head).
qualities passou a ser obrigatório configurar explicitamente na v16 por razões de segurança (allowlist).
remotePatterns é o mecanismo recomendado sobre domains (deprecated v14) por suportar wildcard, protocol, port e query string.
getImageProps evita useState interno, útil para <picture> (art direction) ou CSS image-set() (background).
Sem sizes, o srcset gerado é limitado (1x/2x); com sizes, é completo por largura — a diferença de payload pode ser grande.
SVG, GIF animado e imagens <1KB são candidatos naturais a unoptimized.

Connects To

Font (ch363): mesma filosofia de otimização automática de assets no build.
next.config.js: todas as opções de images vivem lá, complementando as props do componente.
Image (Legacy): versão pré-v13 do componente (renomeado de next/image para next/legacy/image), não coberta neste lote.