--- 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 juste avant le noeud de référence en tant qu'enfant du nœud parent spécifié. Si l'enfant donné est une référence à un noeud existant dans le document, insertBefore() le déplace vers sa nouvelle position (il n'est pas nécessaire de supprimer le noeud de son parent avant son ajout à un autre noeud).

Cela signifie que le noeud ne peut pas être à 2 points du document simultanément. Donc, si le noeud a déjà un parent, le noeud est d'abord supprimé puis inséré dans la nouvelle position. La méthode {{domxref("Node.cloneNode()")}} peut être utilisée pour réaliser une copie du noeud avant son ajout sous le nouveau parent. Notez que les copies faites avec cloneNode ne seront pas automatiquement synchronisées.

Si le noeud de référence est null , le noeud spécifié est ajouté à la fin de la liste des enfants du noeud parent spécifié.

Si l'enfant donné est un {{domxref("DocumentFragment")}}, le contenu entier du {{domxref("DocumentFragment")}} est déplacé dans la liste des enfants du noeud parent spécifié.

Syntaxe

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

Si referenceNode vaut null, newNode est inséré à la fin de la liste des nœuds enfants.

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 retournée

La valeur renvoyée est l'enfant ajouté sauf si le newNode est un {{domxref("DocumentFragment")}}, auquel cas, le {{domxref("DocumentFragment")}} vide est retourné.

Exemple

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

<script>
// Crée un nouveau noeud à insérer
var newNode = document.createElement("span");

// Obtient une référence sur le noeud parent
var parentDiv = document.getElementById("childElement").parentNode;

// Commence le cas test [ 1 ] : un childElement existe --> tout fonctionne correctement
var sp2 = document.getElementById("childElement");
parentDiv.insertBefore(newNode, sp2);
// Fin du cas test [ 1 ]

// Commence le cas test [ 2 ] : childElement est d'un Type indéfini
var sp2 = undefined; // Il n'existe pas de noeud à l'ID "childElement"
parentDiv.insertBefore(newNode, sp2); // Fusion dynamique implicite pour le type du noeud
// Fin du cas test [ 2 ]

// Commence le cas test [ 3 ] : childElement est d'un Type "undefined" (string) (chaîne de caractères)
var sp2 = "undefined"; //  Il n'existe pas de noeud à l'ID "childElement" 
parentDiv.insertBefore(newNode, sp2); // Génère "Type Error: Invalid Argument" (Erreur du Type : Argument non valide) 
// Fin du cas test [ 3 ]
</script>

insertedNode Le noeud en cours d'insertion, c'est-à-dire newNode
parentNode Le parent du nouveau noeud inséré.
newNode Le noeud à insérer.
referenceNode Le noeud devant lequel le newNode est inséré.

Exemple

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

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

// Obtient une référence à l'élément avant lequel nous voulons insérer
var sp2 = document.getElementById("childElement");
// Obtient une référence à l'élément parent
var parentDiv = sp2.parentNode;

// Insère le nouvel élément dans le DOM 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

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

// Obtenir une référence à l'élément dans lequel nous voulons insérer un nouveau noeud
var parentElement = document.getElementById('parentElement');
// Obtenir une référence au premier enfant
var theFirstChild = parentElement.firstChild;

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

// Insérer 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.

Compatibilité des navigateurs

Feature	Chrome	Edge	Firefox (Gecko)	Internet Explorer	Opera	Safari (WebKit)
Basic support	1.0	{{CompatVersionUnknown}}	{{CompatVersionUnknown}}	{{CompatVersionUnknown}}	{{CompatVersionUnknown}}	{{CompatVersionUnknown}}

Feature	Android	Edge	Firefox Mobile (Gecko)	IE Phone	Opera Mobile	Safari Mobile
Basic support	{{CompatUnknown}}	{{CompatVersionUnknown}}	{{CompatUnknown}}	{{CompatUnknown}}	{{CompatUnknown}}	{{CompatUnknown}}

Spécifications

Spécification	Statut	Commentaire
{{SpecName('DOM WHATWG','#dom-node-insertbefore','Node.insertBefore')}}	{{Spec2('DOM WHATWG')}}	Corrige les erreurs dans l'algorithme d'insertion
{{SpecName('DOM4','#dom-node-insertbefore','Node.insertBefore')}}	{{Spec2('DOM4')}}	Décrit l'algorithme plus en détail
{{SpecName('DOM3 Core','core.html#ID-952280727','Node.insertBefore')}}	{{Spec2('DOM3 Core')}}	Pas de changement notable
{{SpecName('DOM2 Core','core.html#ID-952280727','Node.insertBefore')}}	{{Spec2('DOM2 Core')}}	Pas de changement notable
{{SpecName('DOM1','level-one-core.html#method-insertBefore','Node.insertBefore')}}	{{Spec2('DOM1')}}	Définition initiale