Corrigir e Identificar Problemas de Cumulative Layout Shift (CLS)

Antes de alterar qualquer coisa, confirme que você realmente tem um problema de CLS. Faça login no Google Search Console, navegue até Core Web Vitals e verifique tanto em dispositivos móveis quanto em computadores.

Se o Google estiver sinalizando URLs com "Problema de CLS: mais de 0.25" ou "Problema de CLS: mais de 0.1", você tem a confirmação do Chrome User Experience Report (CrUX) de que usuários reais estão enfrentando mudanças de layout no seu site.

Diferente do LCP e do INP, onde o poder de processamento bruto e a velocidade da rede são importantes, os problemas de CLS podem ser específicos do dispositivo ou do tamanho da tela. Quando um problema semelhante afeta dispositivos móveis e computadores (imagens sem tamanho, trocas de fonte, conteúdo injetado) devido ao tamanho da tela, o computador pode relatar um valor de CLS muito maior (porque uma parte maior da viewport visível pode ser afetada). O Search Console agrupa os URLs, então ele informa quais tipos de página são afetados, mas não quais elementos estão mudando. Para isso, você precisa de Real User Monitoring.

O Search Console confirma que o problema existe, mas quase não lhe dá nada com o que trabalhar. Você precisa descobrir quais elementos estão mudando, em quais páginas e sob quais condições. Para isso, você precisa de uma ferramenta de RUM.

Eu construí o CoreDash para responder exatamente a essas perguntas. Você adiciona uma tag de script e ele começa a coletar dados de atribuição de CLS de todos os visitantes reais. O ponto de dados chave para a depuração do CLS é o elemento em mudança: o nó do DOM real que se moveu. Sem essa informação, você está depurando às cegas.

Encontrar elementos em mudança

Comece analisando seus dados de CLS agrupados por elemento. No CoreDash, navegue até a página de CLS e veja a tabela de dados classificada por "CLS by Element". Isso mostra quais elementos causam a maior mudança de layout em todos os seus visitantes. Clique no pior para filtrar todas as métricas para páginas em que esse elemento mudou.

Descobrir quais páginas são afetadas

Após filtrar pelo elemento em mudança mais impactante, verifique a divisão de URLs. Os problemas de CLS podem afetar todo o site ou todo o template. Agora sabemos se o CLS está agrupado em tipos de páginas específicos: páginas de produtos com galerias de imagens, postagens de blog com espaços de anúncios ou landing pages com animações hero. Saber quais páginas falham diz a você onde focar.

Verificar visitantes novos vs. visitantes recorrentes

Esta é outra verificação rápida que faço e que importa mais do que a maioria das pessoas pensa. O CLS por troca de fonte (font-swap) só acontece quando a fonte não está em cache. O CLS de imagens devido a width: auto só acontece quando a imagem não está no cache do navegador. Se o seu CLS for muito pior para visitantes de primeira viagem, você está lidando com uma mudança dependente do cache que você, como desenvolvedor, nunca verá na sua própria máquina, a menos que desative o cache (dica: sempre desative o cache do Chrome... mas essa é outra história para outro dia).

Verificar tipos de dispositivos e tamanhos de viewport

O CLS normalmente mostra um padrão de mobile/desktop diferente do LCP e do INP. Layouts responsivos podem introduzir mudanças que só aparecem em larguras e alturas específicas da viewport. Um espaço de anúncio que causou problemas no desktop pode nem estar na viewport móvel. Um menu de navegação pode ser animado de forma diferente em breakpoints menores. Agrupe seus dados de CLS por tipo de dispositivo para saber onde eles acontecem.

Seus dados de RUM lhe disseram quais elementos mudam e por quê. Agora reproduza o problema localmente e descubra o que o está causando.

Usar o Core Web Vitals Visualizer

A maneira mais rápida de ver as mudanças de layout é com a extensão para Chrome Core Web Vitals Visualizer. Carregue a página, clique no ícone da extensão e recarregue. Cada mudança de layout é destacada com uma sobreposição colorida mostrando exatamente o que se moveu e em quanto. Eu uso isso como meu primeiro passo antes de abrir o painel de Performance porque dá uma resposta visual imediata.

Replicar as condições no Chrome e verificar as capturas de tela de rede

Os problemas de CLS muitas vezes são invisíveis com um cache aquecido. Abra o DevTools, desative o cache na guia Network e limite a conexão para "Slow 4G" (a minha favorita, ela lhe mostrará o CLS causado por condições de corrida). Agora clique no ícone de engrenagem e desative o cache (enquanto o DevTools estiver aberto). Isso simula as condições que os seus visitantes de primeira viagem experimentam. Vá para a guia Network e ative as capturas de tela. Agora recarregue a página e observe as mudanças.

Usar o painel de Performance do Chrome

A maioria das mudanças de layout é fácil de detectar quando você sabe como, mas às vezes elas vão escapar de você. Essa é a hora de abrir o Chrome DevTools (Ctrl+Shift+I) e ir para o painel de Performance para depuração detalhada. Pressione Ctrl+Shift+E para recarregar e gravar. Depois que a página for carregada, role para cima e para baixo algumas vezes. Pare a gravação.

Procure pela trilha de "Layout Shifts". Cada mudança aparece como um bloco colorido. Clique em uma mudança para ver:

• The shifting node: o elemento do DOM que se moveu
• The shift score: a fração de impacto multiplicada pela fração de distância
• hadRecentInput: se a entrada do usuário precedeu a mudança (cliques e toques ganham um período de carência de 500 ms, mas a rolagem não)

Preste atenção a quando as mudanças acontecem. Mudanças durante o carregamento da página apontam para imagens sem tamanho, trocas de fontes ou transições de CSS. Mudanças durante a rolagem apontam para animações acionadas por rolagem usando propriedades de layout.

Teste rápido: desativar todas as transições

As transições de CSS que animam propriedades de layout são uma causa furtiva de CLS porque elas só mudam durante a fase de carregamento e são difíceis de reproduzir. Cole este snippet no console, recarregue a página de forma forçada com o cache desativado e compare o CLS:

document.head.insertAdjacentHTML('beforeend',
  '<style>*{transition-property:none!important}</style>');

Se o seu CLS cair após desativar as transições, você encontrou a causa. Use o guia de depuração de transições de CSS para encontrar as transições específicas responsáveis.

const observer = new PerformanceObserver((list) => {
  for (const entry of list.getEntries()) {
    if (!entry.hadRecentInput) {
      console.log('Layout shift:', {
        value: entry.value,
        sources: entry.sources?.map(s => ({
          node: s.node,
          previousRect: s.previousRect,
          currentRect: s.currentRect
        }))
      });
    }
  }
});
observer.observe({ type: 'layout-shift', buffered: true });

Você sabe quais elementos mudam e por quê. É hora de corrigi-los. O CLS não tem fases sequenciais como o LCP. Em vez disso, as mudanças de layout têm categorias de causas distintas. Aqui estão as mais comuns, na ordem em que as encontro durante as auditorias.

1. Imagens, Vídeos e Iframes Sem Dimensões

Esta é a causa número um de CLS na web. O Web Almanac de 2025 relata que 62% das páginas móveis têm pelo menos uma imagem sem tamanho. A correção: inclua sempre os atributos width e height nas tags <img>, <video> e <iframe>.

<img src="hero.jpg" width="800" height="450" alt="Description">

<style>
img {
    height: auto;
    max-width: 100%;
}
</style>

Cuidado com width: auto no seu CSS. Esta única declaração anula o cálculo de proporção do navegador e causa mudanças de layout, mesmo quando você define width e height no HTML. Eu vi isso em dezenas de sites. O desenvolvedor fez tudo certo na marcação, mas uma regra global de CSS como img { width: auto; height: auto; max-width: 100%; } desfez tudo. Para obter a explicação completa, consulte corrigir mudança de layout causada por imagens de redimensionamento automático. Para um guia completo cobrindo todas as causas de CLS de imagens e mídias (vídeos, iframes, direção de arte, imagens responsivas, carregamento lento, placeholders), veja Como Imagens e Mídias Causam Layout Shift.

2. Trocas de Web Fonts

Quando uma web font é carregada e substitui a fonte de fallback, a diferença de tamanho causa uma mudança de layout. O Web Almanac de 2025 mostra que apenas 11% das páginas fazem preload de web fonts. Isso significa que a grande maioria dos sites é vulnerável ao CLS de troca de fontes.

A correção tem duas partes. Primeiro, faça com que a fonte de fallback corresponda às dimensões da web font usando substituições de métricas (metric overrides):

<style>
@font-face {
    font-family: 'My Font Fallback';
    src: local('Arial');
    size-adjust: 105.2%;
    ascent-override: 93%;
    descent-override: 24%;
    line-gap-override: 0%;
}

@font-face {
    font-family: 'My Font';
    src: url('/fonts/myfont.woff2') format('woff2');
    font-display: swap;
}

body {
    font-family: 'My Font', 'My Font Fallback', sans-serif;
}
</style>

Use um Gerador de Fonte de Fallback para calcular os valores de substituição corretos para o seu par de fontes. Segundo, acelere a entrega: hospede as suas fontes localmente, faça preload do seu arquivo de fonte crítico e use WOFF2 com subsetting. Para uma estratégia completa, veja carregamento responsivo de web font e garantir que o texto permaneça visível durante o carregamento da web font.

3. Animações e Transições de CSS

De acordo com o Web Almanac de 2025, 40% das páginas móveis executam animações não compostas. Estas animam propriedades como width, height, top, left, margin e padding que desencadeiam recálculo de layout em cada frame.

O maior culpado é transition: all. Quando um desenvolvedor escreve transition: all .3s ease, cada mudança de propriedade é animada, incluindo propriedades de layout. Durante o carregamento da página, elementos em transição do seu estado sem estilo para o estado com estilo produzem mudanças de layout que ocorrem intermitentemente e são quase impossíveis de reproduzir de forma consistente. Eu vejo esse padrão o tempo todo.

A correção: substitua as propriedades que acionam o layout por propriedades compostas.

• Use transform: translateY() em vez de top/bottom
• Use transform: translateX() em vez de left/right
• Use transform: scale() em vez de width/height
• Use opacity em vez de visibility combinado com mudanças de altura
• Nunca use transition: all. Especifique a propriedade exata: transition: background-color .2s ease

O transform e opacity são executados inteiramente na thread de composição e nunca acionam o layout. Para o processo completo de depuração, veja mudança de layout causada por transições de CSS.

4. Anúncios, Embeds e Conteúdo Injetado Dinamicamente

Anúncios carregam tarde e empurram o conteúdo para baixo. Banners de consentimento de cookies aparecem e mudam a página. Solicitações AJAX injetam novo conteúdo sem reservar espaço primeiro. Esses são todos o mesmo problema: algo aparece na página que o navegador não conhecia no momento da renderização.

A correção para todos estes é reservar espaço. Para espaços de anúncios, defina uma min-height correspondente ao tamanho esperado do anúncio:

<style>
.ad-slot {
    min-height: 250px;
    contain: layout style;
}
@media (min-width: 600px) {
    .ad-slot { min-height: 90px; }
}
</style>

A declaração contain: layout style isola o contêiner do anúncio do resto da página. Para banners de cookies, use position: fixed para sobrepor em vez de empurrar o conteúdo para baixo. Para conteúdo AJAX, reserve espaço com min-height. Você não precisa de um palpite exato: uma incompatibilidade de 50px é muito menos CLS do que uma mudança de 400px por falta de reserva.

Para embeds de terceiros como YouTube, Google Maps e widgets de chat, use o padrão de fachada (facade pattern): mostre um placeholder estático e carregue o embed real apenas quando o usuário interagir com ele. Zero CLS, zero recursos desperdiçados.

5. Mudanças de Layout Acionadas por Rolagem

Esta é a causa de CLS que o Lighthouse nunca pegará. O Lighthouse não rola a página, então mudanças de layout acionadas por rolagem são completamente invisíveis nos testes de laboratório. A única maneira de encontrá-las é com dados de RUM ou gravando um rastreamento no painel de Performance enquanto rola manualmente.

O exemplo mais comum é um cabeçalho que se oculta na rolagem e que anima a propriedade top. Aqui está o que a maioria dos desenvolvedores não sabe: a rolagem não é uma entrada de exclusão na especificação de Layout Instability. Cliques e toques têm um período de carência de 500 ms. A rolagem não. Toda mudança de layout acionada pela rolagem conta para a sua pontuação de CLS.

A correção: use transform: translateY() em vez de top para qualquer animação acionada por rolagem. O mesmo se aplica a efeitos de parallax, barras de navegação que encolhem e barras de progresso vinculadas à rolagem. Se ele se move na rolagem, anime com transform. Para o passo a passo completo com exemplos em vídeo, veja como animações acionadas por rolagem causam CLS.