InsertBefore

insertBefore is a DOM method used to insert a node into a parent before a specified reference child. It is commonly called on a parent node, with the syntax: parentNode.insertBefore(newNode, referenceNode).

Behavior and scope: The operation inserts newNode as a child of parentNode before referenceNode. If referenceNode is null, newNode is appended to the end of the parent's children. If newNode already exists in the document, it is moved to the new position. If newNode is a DocumentFragment, all of its children are inserted in order and the fragment is cleared.

Return value: The method returns the node that was inserted (often newNode).

Notes on usage: insertBefore is a standard operation in the DOM and is widely supported across modern browsers. It can be used with element nodes as well as other node types, and it works in conjunction with other DOM manipulation methods like appendChild and replaceChild.

Error handling: If referenceNode is not a child of the same parent on which insertBefore is called, a DOMException is raised. If the insertion would create an invalid DOM tree, a DOMException may also be raised.

Examples:

- Inserting before a specific child: var ul = document.querySelector('ul'); var li = document.createElement('li'); li.textContent = 'New item'; var ref = ul.querySelector('li.existing'); ul.insertBefore(li, ref);

- Appending to the end: ul.insertBefore(li, null);

- Moving an existing node: var anotherRef = ul.querySelector('li.other'); ul.insertBefore(li, anotherRef); (li is moved from its previous position to before anotherRef)

See also: appendChild, replaceChild, insertAdjacentElement.