Document: createElement() method

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

Em um documento HTML, o método document.createElement() cria o elemento HTML especificado por tagName, ou um HTMLUnknownElement se tagName não for conhecido.

Sintaxe

js
createElement(tagName)
createElement(tagName, options)

Parâmetros

tagName

Uma string que especifica o tipo do elemento que será criado. O nodeName do elemento é criado com o valor de tagName. Não use nomes qualificados (como "html:a") com este método. Quando chamado em um documento HTML, createElement() converte tagName para letras minúsculas antes de criar o elemento. No Firefox, Opera, e Chrome, createElement(null) funciona como createElement("null").

options Optional

Um objeto com as seguintes propriedades:

is

O nome da tag de um elemento customizado previamente definido via customElements.define(). Veja Web component example para mais detalhes.

Valor retornado

O novo Element.

Nota: Um novo HTMLElement se o documento é um HTMLDocument, que é na maioria dos casos. Caso contrário, um novo Element é retornado.

Exemplos

Exemplo básico

Isto cria uma nova <div> e insere isso antes do elemento com a ID "div1".

HTML

html
<!doctype html>
<html lang="pt-BR">
  <head>
    <meta charset="UTF-8" />
    <title>Trabalhando com elementos</title>
  </head>
  <body>
    <div id="div1">O texto acima foi criado dinamicamente.</div>
  </body>
</html>

JavaScript

js
document.body.onload = addElement;

function addElement() {
  // cria um novo elemento div
  const newDiv = document.createElement("div");

  // e adiciona algum conteúdo ao elemento
  const newContent = document.createTextNode("Hi there and greetings!");

  // adiciona o "text node" para o div recém criado
  newDiv.appendChild(newContent);

  // adiciona o elemento recém criado e seu conteúdo dentro do DOM
  const currentDiv = document.getElementById("div1");
  document.body.insertBefore(newDiv, currentDiv);
}

Resultado

Exemplo com Web Component

O código a seguir foi retirado do nosso exemplo expanding-list-web-component (ver também ao vivo). Neste caso, nosso elemento customizado estende o HTMLUListElement, que representa o elemento <ul>.

js
// Cria uma classe para o elemento
class ExpandingList extends HTMLUListElement {
  constructor() {
    // Chama sempre o primeiro no construtor
    super();

    // a definição do construtor foi deixada de fora para resumir.
    // …
  }
}

// Definir o novo elemento
customElements.define("expanding-list", ExpandingList, { extends: "ul" });

Se nós queremos criar uma instância deste elemento programaticamente, nós iremos utilizar a chamada do seguinte modo:

js
let expandingList = document.createElement("ul", { is: "expanding-list" });

O novo elemento receberá um atributo is cujo valor é o nome da tag do elemento customizado.

Nota: Para efeitos de compatibilidade com versões anteriores dos Custom Elements, alguns navegadores irão permitir você passar uma string aqui em vez de um objeto, onde o valor da string é o nome da tag do elemento customizado.

Especificações

Specification
DOM Standard
# ref-for-dom-document-createelement①

Compatibilidade dos navegadores

BCD tables only load in the browser

Veja também