Encontrar e corrigir problemas de Cumulative Layout Shift (CLS)

Antes de alterar o que quer que seja, confirme se tem realmente um problema de CLS. Aceda ao Google Search Console, vá a Core Web Vitals e verifique tanto em telemóvel como em desktop.

Se o Google estiver a assinalar URLs com «Problema de CLS: mais de 0,25» ou «Problema de CLS: mais de 0,1», tem a confirmação do Chrome User Experience Report (CrUX) de que utilizadores reais estão a sofrer layout shifts no site.

Ao contrário do LCP e do INP, onde o poder de processamento e a velocidade de rede são determinantes, os problemas de CLS podem ser específicos do dispositivo ou do tamanho do ecrã. Quando um problema semelhante afeta o telemóvel e o desktop (imagens sem dimensões, trocas de fontes, conteúdo injetado), o desktop pode reportar um valor de CLS muito mais elevado devido ao tamanho do ecrã (uma vez que uma área maior do viewport visível pode ser afetada). O Search Console agrupa URLs, por isso diz-lhe que tipos de página são afetados, mas não quais os elementos que se estão a mover. Para isso, precisa de Real User Monitoring.

O Search Console confirma a existência do problema, mas quase não dá pistas para trabalhar. Precisa de descobrir que elementos estão a mexer-se, em que páginas e sob que condições. Para isso, precisa de uma ferramenta de RUM.

Criei o CoreDash exatamente para responder a estas perguntas. Adiciona uma tag de script e a ferramenta começa a recolher dados de atribuição de CLS de cada visitante real. O dado fundamental para o debug de CLS é o elemento em desvio: o nó do DOM que realmente se moveu. Sem essa informação, está a fazer debug às cegas.

Encontrar elementos em desvio

Comece por analisar os dados de CLS agrupados por elemento. No CoreDash, aceda à página de CLS e veja a tabela de dados ordenada por «CLS by Element». Isto mostra que elementos causam mais layout shift em todos os visitantes. Clique no pior para filtrar todas as métricas para as páginas onde esse elemento se moveu.

Identificar as páginas afetadas

Depois de filtrar pelo elemento em desvio com maior impacto, analise o detalhe por URL. Os problemas de CLS podem afetar todo o site ou modelos específicos. Agora já sabemos se o CLS está concentrado em tipos de página específicos: páginas de produto com galerias de imagens, artigos de blog com blocos de anúncios ou landing pages com animações na secção hero. Saber que páginas falham indica-lhe onde se focar.

Comparar novos visitantes com visitantes recorrentes

Esta é outra verificação rápida que faço e tem muito mais importância do que a maioria pensa. O CLS por troca de fontes 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á na cache do browser. Se o CLS for muito pior para novos visitantes, está perante um desvio dependente da cache que você, como programador, nunca verá na sua máquina a menos que desative a cache (dica: desative sempre a cache do Chrome... mas isso fica para outro dia).

Verificar tipos de dispositivo e tamanhos de viewport

O CLS mostra tipicamente um padrão mobile/desktop diferente do LCP e do INP. Os layouts responsivos podem introduzir desvios que só surgem em larguras e alturas de viewport específicas. Um bloco de anúncios problemático em desktop pode nem estar no viewport em telemóvel. Um menu de navegação pode animar de forma diferente em breakpoints menores. Agrupe os dados de CLS por tipo de dispositivo para saber onde ocorrem.

Os dados de RUM já indicaram que elementos sofrem desvios e porquê. Agora, reproduza o problema localmente e descubra o que o está a causar.

Utilizar o Core Web Vitals Visualizer

A forma mais rápida de ver layout shifts é com a extensão de Chrome Core Web Vitals Visualizer. Carregue a página, clique no ícone da extensão e recarregue. Cada layout shift é destacado com uma sobreposição colorida que mostra exatamente o que se moveu e quanto. Utilizo isto como primeiro passo antes de abrir o painel Performance, porque dá uma resposta visual imediata.

Replicar as condições no Chrome e verificar os screenshots de rede

Os problemas de CLS são muitas vezes invisíveis com a cache quente. Abra as DevTools, desative a cache no separador Network e limite a ligação para «Slow 4G» (a minha opção favorita; mostra o CLS provocado por race conditions). Agora clique no ícone de roda dentada e desative a cache (com as DevTools abertas). Isto simula as condições que os novos visitantes experienciam. Vá ao separador Network e ative os screenshots. Agora recarregue a página e fique atento aos desvios.

Utilizar o painel Performance do Chrome

A maioria dos layout shifts é fácil de identificar quando se sabe como procurar, mas alguns teimam em escapar. É nessa altura que deve abrir as DevTools do Chrome (Ctrl+Shift+I) e ir ao painel Performance para uma análise detalhada. Prima Ctrl+Shift+E para recarregar e gravar. Depois de a página carregar, faça scroll para cima e para baixo algumas vezes. Pare a gravação.

Procure a faixa «Layout Shifts». Cada desvio aparece como um bloco colorido. Clique num desvio para ver:

• O nó em desvio: o elemento do DOM que se moveu
• A pontuação do desvio: impact fraction multiplicada pela distance fraction
• hadRecentInput: se uma ação do utilizador antecedeu o desvio (cliques e toques têm uma tolerância de 500 ms, mas o scroll não)

Preste atenção ao momento em que os desvios acontecem. Desvios durante o carregamento da página apontam para imagens sem dimensões, trocas de fontes ou transições de CSS. Desvios durante o scroll apontam para animações ativadas por scroll que utilizam 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 traiçoeira de CLS, porque só provocam desvios durante a fase de carregamento e são difíceis de reproduzir. Cole este snippet na consola, force o recarregamento da página com a cache desativada e compare o CLS:

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

Se o CLS descer depois de desativar as transições, encontrou a causa. Utilize o guia de depuração de transições de CSS para encontrar as transições específicas responsáveis.

Já sabe que elementos se movem e porquê. É altura de os corrigir. O CLS não tem fases sequenciais como o LCP. Em vez disso, os layout shifts dividem-se em categorias de causas distintas. Eis as mais comuns, pela ordem em que as encontro nas 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 indica que 62% das páginas em dispositivos móveis têm pelo menos uma imagem sem dimensões. A soluçã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 o width: auto no CSS. Esta única declaração anula o cálculo da proporção feito pelo browser e provoca layout shifts mesmo que tenha definido a largura e a altura no HTML. Já vi isto em dezenas de sites. O programador fez tudo bem no markup, mas uma regra global de CSS como img { width: auto; height: auto; max-width: 100%; } deitou tudo a perder. Para a explicação completa, consulte como corrigir layout shifts causados por imagens com dimensionamento automático. Para um guia completo que cobre todas as causas de CLS em imagens e media (vídeos, iframes, art direction, imagens responsivas, lazy loading, placeholders), consulte Como as imagens e os media causam layout shift.

2. Trocas de web fonts

Quando uma web font carrega e substitui a fonte de fallback, a diferença de dimensões provoca um layout shift. 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 está vulnerável a CLS por troca de fontes.

A correção divide-se em duas partes. Primeiro, faça com que a fonte de fallback coincida com as dimensões da web font através de 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>

Utilize um Fallback Font Generator para calcular os valores de override corretos para a combinação de fontes. Em segundo lugar, acelere a entrega: aloje as suas próprias fontes, faça preload do ficheiro de fonte crítico e utilize WOFF2 com subsetting. Para uma estratégia completa, consulte carregamento responsivo de web fonts e garantir que o texto permanece visível durante o carregamento de web fonts.

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

De acordo com o Web Almanac de 2025, 40% das páginas em dispositivos móveis executam animações não compostas (non-composited). Estas animam propriedades como width, height, top, left, margin e padding, que despoletam recalculações de layout em cada frame.

O problema mais comum é o transition: all. Quando um programador escreve transition: all .3s ease, qualquer alteração de propriedade é animada, incluindo propriedades de layout. Durante o carregamento da página, os elementos que transitam do seu estado não formatado para o formatado produzem layout shifts intermitentes e quase impossíveis de reproduzir de forma consistente. Vejo este padrão constantemente.

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

• Utilize transform: translateY() em vez de top/bottom
• Utilize transform: translateX() em vez de left/right
• Utilize transform: scale() em vez de width/height
• Utilize opacity em vez de visibility combinada com alterações de altura
• Nunca utilize transition: all. Especifique a propriedade exata: transition: background-color .2s ease

O transform e o opacity correm inteiramente na thread do compositor e nunca acionam o layout. Para o processo completo de debug, consulte layout shifts causados por transições de CSS.

4. Anúncios, embeds e conteúdo injetado dinamicamente

Os anúncios carregam tarde e empurram o conteúdo para baixo. Os banners de consentimento de cookies surgem e desviam a página. Os pedidos AJAX injetam novos conteúdos sem reservar espaço previamente. Tudo isto é o mesmo problema: surge algo na página que o browser desconhecia no momento da renderização.

A solução para todos estes casos é reservar espaço. Nos blocos de anúncios, defina um min-height que corresponda ao tamanho previsto 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 contentor do anúncio do resto da página. Nos banners de cookies, utilize position: fixed para criar uma sobreposição em vez de empurrar o conteúdo. No conteúdo de AJAX, reserve espaço com min-height. Não precisa de acertar à risca: uma diferença de 50px causa muito menos CLS do que um desvio de 400px sem qualquer reserva de espaço.

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

5. Layout shifts provocados pelo scroll

Esta é a causa de CLS que o Lighthouse nunca deteta. O Lighthouse não faz scroll na página, pelo que os layout shifts acionados por scroll são completamente invisíveis em testes de laboratório. A única forma de os encontrar é com dados de RUM ou gravando um trace no painel Performance enquanto faz scroll manual.

O exemplo mais comum é um cabeçalho que se esconde ao fazer scroll e anima a propriedade top. Eis o que a maioria dos programadores não sabe: o scroll não é uma interação excluída na especificação da Layout Instability. Os cliques e toques têm uma tolerância de 500 ms. O scroll não. Qualquer layout shift provocado pelo scroll conta para a pontuação de CLS.

A solução: utilize transform: translateY() em vez de top para qualquer animação acionada por scroll. O mesmo aplica-se a efeitos de parallax, barras de navegação que encolhem e barras de progresso associadas ao scroll. Se se mexe no scroll, anime com transform. Para o passo a passo completo com exemplos em vídeo, veja como as animações acionadas por scroll causam CLS.