Pular para o conteúdo
Documentação do Next.js PT-BR

Otimização de imagens

O componente <Image> do Next.js estende o elemento HTML <img> para oferecer:

  • Otimização de tamanho: Serve automaticamente imagens com o tamanho certo para cada dispositivo, usando formatos modernos como WebP.
  • Estabilidade visual: Evita automaticamente o layout shift enquanto as imagens carregam.
  • Carregamento de página mais rápido: Carrega imagens somente quando entram na viewport, usando o lazy loading nativo do navegador, com placeholders opcionais de blur-up.
  • Flexibilidade de assets: Redimensiona imagens sob demanda, inclusive imagens armazenadas em servidores remotos.

Para começar a usar <Image>, importe-o de next/image e renderize-o dentro de um componente.

app/page.tsx
import Image from 'next/image'

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

A propriedade src pode ser uma imagem local ou remota.

🎥 Assista: Saiba mais sobre como usar next/image → YouTube (9 minutos).

Imagens locais

Você pode armazenar arquivos estáticos, como imagens e fontes, em uma pasta chamada public na raiz do projeto. Os arquivos dentro de public podem ser referenciados no código a partir da URL base (/).

Estrutura de pastas mostrando as pastas app e publicEstrutura de pastas mostrando as pastas app e public
app/page.tsx
import Image from 'next/image'

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

Se a imagem for importada estaticamente, o Next.js determina automaticamente a width e a height intrínsecas. Esses valores são usados para calcular a proporção da imagem e evitar o Cumulative Layout Shift enquanto ela carrega.

app/page.tsx
import Image from 'next/image'
import ProfileImage from './profile.png'

export default function Page() {
  return (
    <Image
      src={ProfileImage}
      alt="Picture of the author"
      // width={500} automatically provided
      // height={500} automatically provided
      // blurDataURL="data:..." automatically provided
      // placeholder="blur" // Optional blur-up while loading
    />
  )
}

Imagens sem importação estática

Se você não puder usar um import estático para suas imagens, pode usar um import() dinâmico em um Server Component para continuar obtendo width, height e blurDataURL automaticamente:

app/blog/[slug]/page.tsx
import Image from 'next/image'

async function PostImage({
  imageFilename,
  alt,
}: {
  imageFilename: string
  alt: string
}) {
  const { default: image } = await import(
    `../content/blog/images/${imageFilename}`
  )
  // image contains width, height, and blurDataURL
  return <Image src={image} alt={alt} />
}

Se você tiver um alias de caminho configurado (por exemplo @/), pode usá-lo no lugar de um caminho relativo:

const { default: image } = await import(
  `@/content/blog/images/${imageFilename}`
)

O caminho deve incluir um prefixo estático (como ../content/blog/images/). Seja o mais específico possível, pois todos os arquivos que correspondem a esse prefixo são empacotados. Somente os arquivos do diretório especificado são incluídos, então uma entrada externa não consegue sair dele.

Imagens remotas

Para usar uma imagem remota, forneça uma string de URL na propriedade src.

app/page.tsx
import Image from 'next/image'

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

Como o Next.js não tem acesso a arquivos remotos durante o processo de build, você precisa fornecer manualmente as props width, height e, opcionalmente, blurDataURL. width e height são usados para inferir a proporção correta da imagem e evitar o layout shift causado pelo carregamento. Como alternativa, você pode usar a propriedade fill para fazer a imagem preencher o tamanho do elemento pai.

Para permitir com segurança imagens de servidores remotos, você precisa definir uma lista de padrões de URL aceitos em next.config.js. Seja o mais específico possível para evitar uso malicioso. Por exemplo, a configuração a seguir permite somente imagens de um bucket específico do AWS S3:

next.config.ts
import type { NextConfig } from 'next'

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

export default config

Referência da API

Consulte a Referência da API para ver todos os recursos de Next.js Image