Element.before() — Methode · JavaScript-Referenz

Signatur

Element.prototype.before(...nodes)

Beschreibung

Element.before() fügt beliebig viele Node-Objekte oder Zeichenketten als Geschwister unmittelbar vor dem aktuellen Element ein. Zeichenketten werden automatisch in Text-Knoten umgewandelt. Sie werden also nicht als HTML interpretiert, sondern als reiner Text eingefügt.

Die Methode gehört zum Mixin ChildNode und ist deshalb auch an CharacterData (Text, Kommentare) und DocumentType verfügbar. Sie ersetzt das umständlichere Muster parent.insertBefore(neu, element). Man braucht dafür keinen Verweis auf das Elternelement, und mehrere Knoten lassen sich in einem Aufruf einfügen.

Die Knoten werden in der übergebenen Reihenfolge eingefügt. Ist ein übergebener Knoten schon im Dokument, wird er verschoben und nicht kopiert. Hat das Element keinen Elternknoten, passiert nichts und es wird kein Fehler ausgelöst.

Parameter

Name	Typ	Default	Beschreibung
$...nodes	Node \| string		Beliebig viele Knoten oder Zeichenketten, die vor dem Element eingefügt werden. Zeichenketten werden zu `Text`-Knoten. Ohne Argument passiert nichts.

Rückgabewert

Typ

void

Beschreibung

Gibt undefined zurück.

Beispiele

Warnhinweis vor einem Formularfeld einfügen

const input = document.querySelector('#email');
const hint = document.createElement('p');
hint.className = 'hint';
hint.textContent = 'Bitte eine gültige E-Mail-Adresse angeben.';

input.before(hint);
console.log(input.previousElementSibling.textContent);

Bitte eine gültige E-Mail-Adresse angeben.

Mehrere Knoten und Text in einem Aufruf

// <ul><li id="b">B</li></ul>
const b = document.getElementById('b');
const a = document.createElement('li');
a.textContent = 'A';

b.before('Start: ', a);
console.log(b.parentElement.innerHTML);

Start: <li>A</li><li id="b">B</li>

Vorhandenes Element verschieben (Liste umsortieren)

// <ol><li>Eins</li><li>Zwei</li><li>Drei</li></ol>
const items = document.querySelectorAll('ol li');
const drei = items[2];

// "Drei" wird an den Anfang verschoben, nicht kopiert
items[0].before(drei);
console.log([...document.querySelectorAll('ol li')].map(li => li.textContent));

["Drei", "Eins", "Zwei"]

Kein Elternknoten: stiller No-op

const loose = document.createElement('div');
loose.before('Text');
console.log(loose.previousSibling);

null

// Wichtig · Fallstricke

Zeichenketten sind Text, kein HTML: el.before('<b>x</b>') fügt die spitzen Klammern als sichtbaren Text ein. Das schützt vor XSS. Für echtes Markup nimmt man insertAdjacentHTML('beforebegin', …). Das ist bei Nutzereingaben aber ein XSS-Risiko, deshalb nur mit bereinigten Daten verwenden.
Verschieben statt Kopieren: Ein schon eingehängter Knoten wird von seiner alten Position entfernt. Wer eine Kopie braucht, verwendet node.cloneNode(true).
Ohne Elternknoten bewirkt der Aufruf nichts. Am Wurzelelement document.documentElement löst das Einfügen von Elementen einen HierarchyRequestError aus.
Ein HierarchyRequestError tritt auch auf, wenn ein Vorfahre des Elements eingefügt werden soll.
Kompatibilität: wird von allen modernen Browsern unterstützt (Chrome 54+, Firefox 49+, Safari 10+, Edge 17+), nicht aber vom Internet Explorer. Dort braucht man ein Polyfill oder insertBefore.
Mehrere Knoten in einem Aufruf werden intern über ein DocumentFragment eingefügt. Das ist effizienter als mehrere einzelne Aufrufe.

Siehe auch

Element.after() Element.prepend() Element.append() Element.replaceWith() Node.insertBefore() Element.insertAdjacentElement() Element.insertAdjacentHTML()