Lazy loading de imagens com Claude Code: guia seguro para iniciantes

Lazy loading de imagens não é colocar loading="lazy" em todoimg. Se o Claude Code atrasar também a imagem hero, o Largest Contentful Paint, isto é, o momento em que o conteúdo principal aparece, pode piorar. Se todos os thumbnails de produto, galeria e artigos relacionados carregarem antes, o usuário móvel baixa imagens que talvez nunca veja.

Este guia mostra um padrão seguro para iniciantes: lazy loading nativo, hero ou candidato LCP em eager, decoding, fetchpriority, dimensões para evitar CLS, srcset e sizes, IntersectionObserver para casos avançados, placeholders, armadilhas de SEO/UX, medição e prompts seguros para Claude Code. A base técnica foi conferida com a referência MDN doelemento img, Intersection Observer API, web.dev sobrelazy loading nativo de imagens, Core Web Vitals e Chrome sobreLCP request discovery.

Para uma estratégia completa, leia tambémotimização de imagens, skeleton loading eotimização de performance.

Regra principal

Não faça lazy loading do que aparece imediatamente. Use lazy para imagens abaixo da primeira tela e reserve espaço para todas comwidth eheight, ou com umaspect-ratio equivalente.

Local da imagem	loading	fetchpriority	decoding	Proteção
Hero ou candidata LCP	eager ou omitido	Considere high	sync ou async	Descoberta no HTML inicial
Diagrama no meio do artigo	lazy	auto	async	Manter dimensões
Grade de produtos após a primeira tela	lazy	auto	async	Usar srcset e sizes
Carrossel ou scroll infinito	Depende	auto	async	IntersectionObserver se necessário

O erro comum é pensar “imagem pesada precisa ser lazy”. A pergunta correta é se ela participa da primeira visualização útil. A documentação do Chrome sobre LCP recomenda que a imagem LCP seja encontrada cedo, receba prioridade correta e não useloading=lazy.

HTML para copiar

A primeira imagem é hero, então usa eager e alta prioridade. A segunda aparece mais abaixo no artigo ou em uma lista, então usa lazy nativo e decoding assíncrono.

<img
  class="hero-image"
  src="/images/hero/product-dashboard-1200.webp"
  srcset="
    /images/hero/product-dashboard-640.webp 640w,
    /images/hero/product-dashboard-1200.webp 1200w
  "
  sizes="100vw"
  alt="Primeira visão de um painel de produto"
  width="1200"
  height="675"
  loading="eager"
  fetchpriority="high"
  decoding="sync"
/>

<img
  class="article-image"
  src="/images/articles/setup-step-800.webp"
  srcset="
    /images/articles/setup-step-400.webp 400w,
    /images/articles/setup-step-800.webp 800w
  "
  sizes="(max-width: 720px) 100vw, 720px"
  alt="Captura de tela de uma etapa de configuração"
  width="800"
  height="450"
  loading="lazy"
  decoding="async"
/>

decoding="async" é uma dica para o navegador decodificar a imagem sem bloquear tanto outras tarefas de renderização. É um bom padrão para imagens de artigo e thumbnails. Para hero, comparesync easync medindo.

Evitar CLS com CSS

CLS significa Cumulative Layout Shift. Em português simples, mede quanto a página pula enquanto a pessoa lê ou tenta tocar. Se a imagem aparece sem altura reservada, empurra texto, anúncio, formulário e CTA. Isso afeta conversão, não apenas a nota do Lighthouse.

.image-frame {
  aspect-ratio: 16 / 9;
  background: #f3f4f6;
  overflow: hidden;
}

.image-frame > img {
  display: block;
  width: 100%;
  height: 100%;
  object-fit: cover;
}

@media (prefers-reduced-motion: no-preference) {
  .image-frame > img {
    transition: opacity 180ms ease-out;
  }
}

Se o CMS conhece largura e altura originais, salve esses valores e envie ao template. Se a imagem vem de terceiros e o tamanho é desconhecido, reserve um contêiner estável comaspect-ratio e ajuste a imagem comobject-fit.

Componente React pequeno

Ao pedir uma alteração React ao Claude Code, coloque a política em um componente. Imagens prioritárias ficam eager, imagens comuns ficam lazy e todas mantêm dimensões.

type SmartImageProps = {
  src: string;
  srcSet?: string;
  sizes?: string;
  alt: string;
  width: number;
  height: number;
  priority?: boolean;
  className?: string;
};

export function SmartImage({
  src,
  srcSet,
  sizes,
  alt,
  width,
  height,
  priority = false,
  className,
}: SmartImageProps) {
  const loading = priority ? "eager" : "lazy";
  const fetchPriority = priority ? "high" : "auto";
  const decoding = priority ? "sync" : "async";

  return (
    <span
      className={`image-frame ${className ?? ""}`}
      style={{ aspectRatio: `${width} / ${height}` }}
    >
      <img
        src={src}
        srcSet={srcSet}
        sizes={sizes}
        alt={alt}
        width={width}
        height={height}
        loading={loading}
        fetchPriority={fetchPriority}
        decoding={decoding}
      />
    </span>
  );
}

O componente é simples de propósito. Ele não esconde imagem importante atrás de JavaScript e pode ser adaptado para Next.js, Astro ou componentes de CMS.

Casos de uso de produto

O primeiro caso é uma grade ecommerce. Os primeiros produtos podem estar na primeira tela, então não marque tudo como lazy. Recomendações, avaliações, histórico e itens da segunda tela são candidatos melhores. O erro concreto é colocarfetchpriority="high" em todos os thumbnails; o navegador perde a noção do que é urgente.

O segundo caso é um tutorial ou artigo editorial. A capa costuma ser candidata LCP e deve ficar eager. Capturas de etapas, diagramas depois de blocos de código e cards relacionados podem ser lazy. O erro concreto é usar placeholder borrado como fundo e deixar oalt real vazio. Se a imagem tem significado, SEO e leitores de tela precisam desse texto.

O terceiro caso é um dashboard SaaS. Avatares, logos de clientes, thumbnails de relatórios e capturas de auditoria podem aparecer em listas longas. Lazy loading nas linhas fora da tela ajuda, mas não atrase o gráfico principal, a ilustração de onboarding ou a imagem perto do CTA. Para medir CTA e receita, conecte comimplementação de analytics.

Também há galerias e carrosséis horizontais. O lazy nativo geralmente basta, mas IntersectionObserver ajuda quando há contêiner com scroll próprio, slides escondidos ou distância de pré-carregamento personalizada.

Quando usar IntersectionObserver

Use lazy nativo primeiro. Use IntersectionObserver quando precisar carregar 300px antes, trocardata-src, remover classe de placeholder ou observar um contêiner específico.

<img
  class="js-lazy-image"
  src="/images/placeholders/report-thumb.svg"
  data-src="/images/reports/report-2026.webp"
  data-srcset="/images/reports/report-2026.webp 1x"
  alt="Miniatura do relatório mensal"
  width="640"
  height="360"
/>

const lazyImages = document.querySelectorAll("img[data-src]");

function loadImage(img) {
  img.src = img.dataset.src;

  if (img.dataset.srcset) {
    img.srcset = img.dataset.srcset;
  }

  img.removeAttribute("data-src");
  img.removeAttribute("data-srcset");
}

if ("IntersectionObserver" in window) {
  const observer = new IntersectionObserver((entries, currentObserver) => {
    entries.forEach((entry) => {
      if (!entry.isIntersecting) return;

      loadImage(entry.target);
      currentObserver.unobserve(entry.target);
    });
  }, {
    rootMargin: "300px 0px",
    threshold: 0.01,
  });

  lazyImages.forEach((image) => observer.observe(image));
} else {
  lazyImages.forEach(loadImage);
}

Mantenha as dimensões também nessa abordagem. Uma imagem comdata-src pode nunca carregar se JavaScript falhar, então não use isso para imagem principal de produto, hero ou imagem essencial para SEO.

Medição

Core Web Vitals acompanha LCP, INP e CLS. Bons limites comuns são LCP até 2,5 segundos, INP até 200 ms e CLS até 0,1. Em lazy loading de imagens, LCP e CLS são os mais sensíveis.

npm install web-vitals

import { onCLS, onINP, onLCP } from "web-vitals";

onLCP((metric) => {
  const lastEntry = metric.entries.at(-1);
  console.log("LCP", metric.value, lastEntry?.element);
});

onCLS((metric) => {
  console.log("CLS", metric.value, metric.entries);
});

onINP((metric) => {
  console.log("INP", metric.value, metric.entries);
});

No Chrome DevTools, veja se o elemento LCP é a hero esperada, se a requisição aparece cedo no HTML e se alguma imagem causa layout shift. Depois de publicar, compare PageSpeed Insights, Search Console e seus eventos.

Prompt seguro para Claude Code

Claude Code troca muitas ocorrências rapidamente. Defina escopo, regras e verificação antes.

{
  "goal": "Adicionar lazy loading seguro para imagens",
  "scope": [
    "Alterar apenas imagens de artigo e listas de produto",
    "Não aplicar lazy a imagens da primeira tela ou candidatas LCP"
  ],
  "rules": [
    "Manter alt, width e height em cada img",
    "Usar loading=\"lazy\" e decoding=\"async\" abaixo da dobra",
    "Usar loading=\"eager\" ou omitir loading na hero",
    "Usar fetchpriority=\"high\" no máximo em uma candidata LCP"
  ],
  "verification": [
    "Verificar MDX e code fences",
    "Inspecionar LCP e CLS no DevTools",
    "Checar no mobile se imagem, texto e CTA não se sobrepõem"
  ]
}

Peça para Claude Code explicar quais imagens não ficaram lazy e por quê. Essa justificativa ajuda na revisão.

Lista de falhas

• Hero, imagem principal de produto ou imagem do CTA superior ficou lazy.
• width eheight foram removidos.
• Todas as imagens receberamfetchpriority="high".
• Variantes desrcset têm proporções diferentes sem art direction.
• Uma imagem de fundo CSS foi tratada comoimg.
• Um diagrama útil ficou comalt vazio.
• Imagens importantes dependem só de JavaScript.
• O placeholder chama mais atenção que o conteúdo real.

CTA e nota de verificação

Lazy loading de imagens não é só pontuação. Ele afeta leitura, visibilidade de CTA, navegação de produtos e primeira ação no app. Para uso individual, comece pelocheatsheet gratuito de Claude Code. Para prompts e templates reutilizáveis, veja apágina de produtos. Para equipes que querem unir performance, SEO, analytics e monetização, usetreinamento e consultoria Claude Code.

Nesta atualização, revisei as fontes oficiais acima e refiz os exemplos com uma regra prática: decidir primeiro quais imagens não devem ser lazy. No fluxo de Masa, o padrão estável foi hero eager, capturas inferiores lazy, dimensões em todas as imagens,srcset para mobile e prompt de Claude Code com falhas e tarefas de medição desde o início.