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.

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

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
# ref-for-dom-document-createelement①

Compatibilidade dos navegadores

Report problems with this compatibility data on GitHub
desktopmobile
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
createElement
options parameter

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
No support
No support
See implementation notes.

Veja também