The prepend() method is a modern DOM manipulation tool that inserts a set of Node objects or string objects as the very first children of an element.

It was introduced to provide a simpler, more readable alternative to the classic parentNode.insertBefore(newNode, parentNode.firstChild) pattern.

1. Syntax and Parameters

The method accepts a variable number of arguments, allowing you to insert multiple items at once.

JavaScript
element.prepend(param1, param2, /* ..., */ paramN);
  • params: These can be Node objects (like elements created via document.createElement) or simple strings. If a string is passed, it is automatically treated as a Text node.
  • Return Value: The method returns undefined.

2. Practical Examples

A. Inserting Elements and Text Simultaneously

One of the most powerful features of prepend() is its ability to mix nodes and strings in a single call.

JavaScript
const list = document.querySelector('#task-list');
const newItem = document.createElement('li');
newItem.textContent = "Morning Yoga";

// Prepending a Node and a raw string
list.prepend(newItem, " - Priority: High");

// Resulting HTML:
// <ul id="task-list">
//   <li>Morning Yoga</li> - Priority: High
//   ... other items ...
// </ul>

B. Moving Existing Elements

If you prepend an element that is already located elsewhere in the DOM, JavaScript will move it rather than clone it. The element is removed from its current position and placed at the start of the target parent.

JavaScript
const header = document.querySelector('header');
const nav = document.querySelector('#main-nav');

// Moves the nav from its current location to the very top of the header
header.prepend(nav);

3. Key Characteristics and “Gotchas”

A. Multiple Arguments

You can pass as many arguments as you like. They will be inserted in the order they appear in the arguments list.

JavaScript
const div = document.createElement('div');
div.prepend('First ', 'Second ', 'Third');
console.log(div.textContent); // "First Second Third"

B. Safety from HTML Injection

Unlike insertAdjacentHTML() or innerHTML, passing a string to prepend() does not parse it as HTML. It is treated as literal text. This makes prepend() inherently safe from XSS (Cross-Site Scripting) attacks when dealing with strings.

JavaScript
const box = document.querySelector('.box');
// This will render the literal tags on screen, not a bold word.
box.prepend("<b>Warning:</b> ");

4. Automatic Moving (Live Nodes)

In the DOM, a node can only exist in one place at a time. If you prepend() an element that is already present in the document, it will be moved from its current position to the new starting position. This is an efficient way to reorder UI elements.

JavaScript
const list = document.querySelector('ul');
const lastItem = list.lastElementChild;

// Moves the last item to the very top
list.prepend(lastItem);

5. Advanced Usage: Prepending to the Document Head

You will often see prepend() used to inject critical CSS or meta tags at the absolute top of the <head> to ensure they are processed before other scripts or styles.

JavaScript
const meta = document.createElement('meta');
meta.name = "viewport";
meta.content = "width=device-width, initial-scale=1";

document.head.prepend(meta);

6. Performance and Batching with DocumentFragments

While prepend() is convenient, prepending many individual elements in a loop can cause “layout thrashing” (repeatedly recalculating the page layout). If you need to prepend a large number of items, use a DocumentFragment to batch the operation.

JavaScript
const list = document.querySelector('ul');
const fragment = document.createDocumentFragment();

['New A', 'New B', 'New C'].forEach(text => {
    const li = document.createElement('li');
    li.textContent = text;
    fragment.append(li);
});

// One single reflow for all three items
list.prepend(fragment);

Categorized in:

JS DOM,