Node.insertBefore

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.

O método Node.insertBefore() insere um nó antes do nó de referência como um filho de um nó pai especificado. Se o filho especificado for uma referência a um nó existente no documento, insertBefore() o moverá de sua posição atual para a nova posição (não há necessidade de remover o nó de seu nó pai antes de anexá-lo a outro nó).

Isso significa que um nó não pode estar em dois pontos do documento simultaneamente. Portanto, se o nó já tiver um pai, o nó será removido pela primeira vez e inserido na nova posição. O Node.cloneNode() pode ser usado para fazer uma cópia do nó antes de anexá-lo ao novo pai. Note que as cópias feitas com cloneNode() não serão automaticamente mantidas em sincronia.

Se o nó de referência for null, o nó especificado será incluído no final da lista de filhos do nó pai especificado.

Se o filho especificado for um DocumentFragment, todo o conteúdo do DocumentFragment será movido para a lista de filhos do nó pai especificado.

Sintaxe

var elementoInserido = elementoPai.insertBefore(novoElemento, elementoDeReferencia);
  • elementoInserido O nó sendo inserido, que é novoElemento
  • elementoPai Pai do nó recentemente inserido.
  • novoElemento O nó a ser inserido.
  • elementoDeReferencia O nó antes do qual o novoElemento será inserido.

Se elementoDeReferencia for null, novoElemento será inserido no fim da lista de nós filhos.

Nota: elementoDeReferencia não é um parâmetro opcional - você deve passar explicitamente um Node ou null. Deixar de fornecer ou passar valores inválidos pode ter comportamento diferente em diferentes versões de navegadores.

Return value

O valor retornado é o filho incluído, exceto quando newNode é um DocumentFragment, caso em que o DocumentFragment vazio é retornado.

Exemplo

html
<div id="elementoPai">
  <span id="elementoFilho">foo bar</span>
</div>

<script>
  // Cria um novo elemento <span> vazio
  var sp1 = document.createElement("span");

  // Guarda a referência do elemento atraś do qual nos queremos inserir o novo elemento
  var sp2 = document.getElementById("elementoFilho");
  // Guarda a referência do elemento pai
  var divPai = sp2.parentNode;

  // Insere o novo elemento no DOM antes de sp2
  divPai.insertBefore(sp1, sp2);
</script>

Não existe um método insertAfter. Mas ele pode ser emulado combinando o método insertBefore com nextSibling.

No exemplo anterior, sp1 poderia ser inserido após sp2 desta forma:

divPai.insertBefore(sp1, sp2.nextSibling);

Se sp2 não possuir um próximo nó, significa que ele deve ser o último filho — sp2.nextSibling retorna null, e sp1 é inserido ao fim da da lista de nós filhos (logo após sp2).

Exemplo 2

Inserir um elemento antes do primeiro nó filho, usando a propriedade firstChild.

js
// Guarda a referêncis do elemento no quela nóe queremos inserir o novo nó
var elementoPai = document.getElementById("elementoPai");
// Guarda a referência do primeiro filho
var primeiroFilho = elementoPai.firstChild;

// Cria um novo elemento
var novoElemento = document.createElement("div");

// Insere o novo elemento antes do primeiro filho
elementoPai.insertBefore(novoElemento, primeiroFilho);

Quando o elemento não possui o primeiro filho, então firstChild é null. O elemento ainda será inserido no pai, mas após o último filho. Pois se o elemento pai não possui primeiro filho, ele também não possui o último filho. Conseqüentemente, o novo elemento será o único elemento após a inserção.

Especificações

Specification
DOM
# dom-node-insertbefore

Compatibilidade com 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
insertBefore

Legend

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

Full support
Full support