element.insertBefore
====================

La méthode **`Node.insertBefore()`** insère un nœud avant un *nœud de référence* en tant qu'enfant d'un *nœud parent* spécifié.

Si le nœud donné existe déjà dans le document, `insertBefore()` le déplace de sa position actuelle vers la nouvelle position. (C'est-à-dire qu'il sera automatiquement retiré de son parent existant avant d'être ajouté au nouveau parent spécifié).

Cela signifie qu'un nœud ne peut pas se trouver simultanément à deux endroits du document.

Syntaxe
-------


```js
var insertedNode = parentNode.insertBefore(newNode, referenceNode);
```


`insertedNode`

Le nœud en cours d'insertion (le même que `newNode`).

`parentNode`

Le parent du nœud nouvellement inséré.

`newNode`

Le nœud à insérer.

`referenceNode`

Le nœud avant lequel `newNode` est inséré. Si c'est `null`, alors `newNode` est inséré à la fin des nœuds enfants de `parentNode`.


**Note :** *`referenceNode`* **n'est pas** un paramètre facultatif — vous devez explicitement transmettre un `Node` ou `null`. Ne pas le fournir ou transmettre des valeurs invalides provoque des comportements différents selon les différentes versions des navigateurs.

### Valeur de retour

Renvoie l'enfant ajouté (sauf si `newNode` est un `DocumentFragment`, auquel cas le `DocumentFragment` vide est renvoyé).

Exemples
--------

### Exemple 1


```html
<div id="parentElement">
  <span id="childElement">foo bar</span>
</div>

<script>
 // Crée le nouveau nœud à insérer
 let newNode = document.createElement("span");

 // Obtient une référence au nœud parent
 let parentDiv = document.getElementById("childElement").parentNode;

 // Commence le cas de test [ 1 ] : Existing childElement (tout fonctionne correctement)
 let sp2 = document.getElementById("childElement");
 parentDiv.insertBefore(newNode, sp2);
 // Fin du cas de test [ 1 ]

 // Commence le cas de test [ 2 ] : childElement est de Type undefined
 let sp2 = undefined; // Noeud non existant de l'id "childElement".
 parentDiv.insertBefore(newNode, sp2); // Transfert dynamique implicite vers le type Node
 // Fin du cas de test [ 2 ]

 // Commence le cas de test [ 3 ] : childElement est de Type "undefined" ( string )
 let sp2 = "undefined"; // Noeud non existant de l'id "childElement".
 parentDiv.insertBefore(newNode, sp2); // Génère "Erreur de type : Argument non valide".
 // Fin du cas de test [ 3 ]
</script>
```

### Exemple 2


```html
<div id="parentElement">
  <span id="childElement">foo bar</span>
</div>

<script>
 // Crée un nouvel élément simple de type <span>
 let sp1 = document.createElement("span");

 // Obtient l'élément de référence
 let sp2 = document.getElementById("childElement");
 // Get the parent element
 let parentDiv = sp2.parentNode;

 // Insert le nouvel élément dans avant sp2
 parentDiv.insertBefore(sp1, sp2);
</script>
```


Il n'existe pas de méthode `insertAfter()`. Il peut être émulé avec une combinaison des méthodes `insertBefore()` et `Node.nextSibling`.

Dans l'exemple ci-dessus, `sp1` pourrait être inséré après `sp2` en utilisant :


```js
parentDiv.insertBefore(sp1, sp2.nextSibling);
```


Si `sp2` n'a pas d'enfant suivant, c'est qu'il est le dernier enfant. Dans ce cas, `sp2.nextSibling` renverra `null` et `sp1` sera donc inséré à la fin de la liste des nœuds enfants (c'est-à-dire immédiatement après `sp2`).

### Exemple 3

Insérer un élément avant le premier élément enfant en utilisant la propriété firstChild.


```js
// Obtient l'élément parent
let parentElement = document.getElementById("parentElement");
// Obtient le premier enfant du parent
let theFirstChild = parentElement.firstChild;

// Crée un nouvel élément
let newElement = document.createElement("div");

// Insert le nouvel élément avant le premier enfant
parentElement.insertBefore(newElement, theFirstChild);
```


Si l'élément n'a pas de premier enfant, alors `firstChild` est `null`. L'élément est toujours ajouté au parent après le dernier enfant. Comme l'élément parent n'avait pas de premier enfant, il n'avait pas non plus de dernier enfant. Par conséquent, le nouvel élément est le seul élément, après l'insertion.

Spécifications
--------------

| Specification |
| --- |
| DOM Standard # dom-node-insertbefore |

Compatibilité des navigateurs
-----------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.