--- title: element.insertBefore slug: Web/API/Node/insertBefore tags: - API - DOM - Enfant - Insertion - Méthodes - Noeud translation_of: Web/API/Node/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

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 {{domxref("DocumentFragment")}}, auquel cas le {{domxref("DocumentFragment")}} vide est renvoyé).

Exemples

Exemple 1

<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

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

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

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.

// 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	Status	Comment
{{SpecName('DOM WHATWG','#dom-node-insertbefore','Node.insertBefore')}}	{{Spec2('DOM WHATWG')}}	Fixes errors in the insertion algorithm
{{SpecName('DOM4','#dom-node-insertbefore','Node.insertBefore')}}	{{Spec2('DOM4')}}	Describes the algorithm in more detail
{{SpecName('DOM3 Core','core.html#ID-952280727','Node.insertBefore')}}	{{Spec2('DOM3 Core')}}	No notable changes
{{SpecName('DOM2 Core','core.html#ID-952280727','Node.insertBefore')}}	{{Spec2('DOM2 Core')}}	No notable changes
{{SpecName('DOM1','level-one-core.html#method-insertBefore','Node.insertBefore')}}	{{Spec2('DOM1')}}	Introduced