Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / JavaScript

document.getElementById — encontrar um elemento pelo ID

document.getElementById(elementId) devolve o elemento com o ID indicado ou null. A pesquisa distingue maiúsculas de minúsculas e percorre os descendentes do documento.

Versão: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Sintaxe

document.getElementById(elementId)

document.getElementById(elementId) é um método do DOM, não faz parte do próprio ECMAScript. Passe um valor id, como "status", sem o prefixo #: o argumento não é um seletor CSS. O resultado é um Element ou null. A pesquisa distingue maiúsculas de minúsculas; um identificador vazio não corresponde a nenhum elemento.

O método pesquisa os descendentes do documento. Um elemento desligado não será encontrado. Se houver IDs duplicados, devolve o primeiro elemento pela ordem da árvore, que não é necessariamente o primeiro a ser criado. Antes de utilizar o resultado, confirme que não é null; faça a pesquisa apenas depois de adicionar o elemento pretendido ao documento.

getElementById também está disponível em DocumentFragment, mas não em objetos Element comuns. A pesquisa no documento não entra em árvores de sombra. O exemplo requer um ambiente DOM de navegador; a existência de uma versão de Node.js, por si só, não confirma a disponibilidade desta API.

Exemplos

{
  const document = globalThis.document.implementation.createHTMLDocument("");
  const item = document.createElement("div");
  item.id = "status";

  console.log(document.getElementById("status") === null);
  document.body.appendChild(item);
  console.log(document.getElementById("status") === item);
  console.log(document.getElementById("Status") === null);
  item.remove();
  console.log(document.getElementById("status") === null);
}

Resultado

true
true
true
true

O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.

Fontes