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 ⁨julho de 2015⁩.

* Some parts of this feature may have varying levels of support.

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.

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

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>.

// 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:

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.