DOMContentLoaded

O evento DOMContentLoaded é acionado quando todo o HTML foi completamente carregado e analisado, sem aguardar pelo CSS, imagens, e subframes para encerrar o carregamento. Um evento muito diferente - load - deve ser usado apenas para detectar uma página completamente carregada. É um engano comum as pessoas usarem load quando DOMContentLoaded seria muito mais apropriado.

Acelerando

Se você quer que o DOM seja analisado o mais rápido possível após uma requisição do usuário, você deve usar recursos do javascript assíncrono e otimizar o carregamento de folhas de estilo pois, caso contrário, a página será carregada mais lentamente pois muitos itens serão carregados paralelamente, atrasando a visualização da página.

Informações gerais

Especificação

HTML5

Interface

Event

Propaga

Sim

Cancelável

Sim (embora especificado como evento simples não-cancelável)

Alvo

Document

Ação Default

Nenhuma.

Propriedades

Exemplo

Básico

<script>
  document.addEventListener("DOMContentLoaded", function(event) {
    console.log("DOM completamente carregado e analisado");
  });
</script>

Forçando o atraso do DOMContentLoaded

<script>
  document.addEventListener("DOMContentLoaded", function(event) {
    console.log("DOM completamente carregado e analisado");
  });

for(var i=0; i<1000000000; i++)
{} // este script síncrono irá o atrasar carregamento do DOM. Então o evento DOMContentLoaded irá ser ativado mais tarde.
</script>

Verificando se o carregamento está completo

DOMContentLoaded pode disparar antes do seu script ser carregado, então é importante validar antes de adicionar um listener.

function doSomething() {
  console.info("DOM carregado");
}

if (document.readyState === "loading") {  // Ainda carregando
  document.addEventListener("DOMContentLoaded", doSomething);
} else {  // `DOMContentLoaded` foi disparado
  doSomething();
}

Compatibilidade entre Navegadores

Propagação para este evento é suportada à partir do Gecko 1.9.2, Chrome 6, e Safari 4.

Cross-browser fallback

O Internet Explorer 8 suporta o evento readystatechange, que pode ser usado para detectar quando o DOM está pronto. Em versões anteriores do Internet Explorer, este estado pode ser detectado tentando executar document.documentElement.doScroll("left"); repetidas vezes; este comando dará erro repetidamente, até que o DOM esteja pronto.

Há também uma abundância de bibliotecas de propósito geral que oferecem métodos cross-browser para detectar se o DOM está pronto.

Eventos Relacionados

• DOMContentLoaded
• readystatechange
• load
• beforeunload
• unload