JavaScript Element moveBefore() Method

What You’ll Learn

Element.moveBefore() is an instance method that moves a node inside the caller as a direct child, before a reference node. Unlike insertBefore(), it preserves focus, animations, popover state, and more (MDN). Learn the MDN toggle demo, null reference append, constraints, feature detection, and five try-it labs aligned with MDN.

Introduction

When you rearrange UI with insertBefore() or prepend(), the browser removes the node and inserts it again. That can reset focus, close popovers, interrupt CSS transitions, and disturb other element state.

moveBefore(movedNode, referenceNode) moves a node to a new position without that remove-and-reinsert cycle (MDN). The node keeps its interactive and visual state—a big win for draggable panels, live video embeds, and modals.

This page is part of JavaScript Element. Compare with before() and append() for other DOM insertion patterns.

Understanding the moveBefore() Method

Calling parent.moveBefore(movedNode, referenceNode) relocates movedNode inside parent, immediately before referenceNode.

• It is an instance method on Element (MDN).
• movedNode must be an Element or CharacterData node.
• referenceNode must be a child of the caller, or null to append.
• Returns undefined (MDN).
• Preserves animation, focus, popover, modal, and loading state (MDN).
• Only works within the same document; connected/disconnected mismatches throw (MDN).
• MutationObserver records a removed node and an added node for the move (MDN).

📝 Syntax

General form of Element.moveBefore (MDN):

moveBefore(movedNode, referenceNode)

Parameters

Return value

Exceptions

• HierarchyRequestError — invalid moves such as cross-document, disconnected nodes, moving an ancestor into a descendant, invalid referenceNode, missing second argument, or wrong node type (MDN).

Common patterns

// MDN toggle: move before section1 or section2
if (mover.nextElementSibling === section1) {
  wrapper.moveBefore(mover, section2);
} else {
  wrapper.moveBefore(mover, section1);
}

// Append to end of a container
section2.moveBefore(mover, null);

// Feature-detect with insertBefore fallback
function moveNode(parent, node, ref) {
  if (typeof parent.moveBefore === "function") {
    parent.moveBefore(node, ref);
  } else {
    parent.insertBefore(node, ref);
  }
}

Examples Gallery

Examples follow MDN Element.moveBefore() patterns. Use View Output or Try It Yourself for each case.

const wrapper = document.getElementById("wrapper");
const section1 = document.getElementById("section1");
const section2 = document.getElementById("section2");
const mover = document.getElementById("mover");

moveBtn.addEventListener("click", () => {
  if (mover.nextElementSibling === section1) {
    wrapper.moveBefore(mover, section2);
  } else {
    wrapper.moveBefore(mover, section1);
  }
});

mover toggles between section positions

const section1 = document.getElementById("section1");
const section2 = document.getElementById("section2");
const mover = document.getElementById("mover");

if (mover.parentElement === section1) {
  section2.moveBefore(mover, null); // append inside section2
} else {
  section1.moveBefore(mover, null); // append inside section1
}

mover appended to other section

const field = document.getElementById("field");
const boxA = document.getElementById("boxA");
const boxB = document.getElementById("boxB");

field.focus();
const hadFocus = document.activeElement === field;

boxB.moveBefore(field, null);

console.log(hadFocus && document.activeElement === field);
// true — focus preserved (MDN)

true

function moveNode(parent, node, ref) {
  if (typeof parent.moveBefore === "function") {
    parent.moveBefore(node, ref);
  } else {
    parent.insertBefore(node, ref);
  }
}

moveNode(section2, mover, null);
console.log("moved with fallback support");

moved with fallback support

const parent = document.getElementById("wrapper");
const supported = typeof parent.moveBefore === "function";

console.log(supported ? "moveBefore available" : "use insertBefore fallback");

if (supported) {
  parent.moveBefore(mover, section1);
}

moveBefore available (or fallback message)

🚀 Common Use Cases

• Dragging panels between columns without losing focus (MDN).
• Moving video or iframe embeds while preserving playback state (MDN demo).
• Reordering list items in a sortable UI with animations intact.
• Keeping popovers and modals open during DOM repositioning.
• Custom elements moved with connectedMoveCallback() instead of disconnect/connect (MDN).
• Progressive enhancement with insertBefore() fallback.

📝 Notes

• Limited availability on MDN — not Baseline; feature-detect before use.
• Returns undefined (MDN).
• referenceNode === null appends at the end of children (MDN).
• Preserves focus, animations, popovers, modals, and loading state (MDN).
• Same-document only; connected/disconnected mismatches throw (MDN).
• Related: before(), append(), matches(), JavaScript hub.

💡 Best Practices