JavaScript Document moveBefore() Method

Beginner
5 min read
Updated: Nov 2026
3 examples
Method
Decorative image with the word MOVEBEFORE

Definition

document.moveBefore(movedNode, referenceNode) moves a node so it becomes a direct child of the Document, placed before referenceNode (or at the end when referenceNode is null). Unlike insertBefore(), it does not remove-and-reinsert — so focus, animations, and similar state can survive the move (MDN).

Pass the required arguments shown below. Check return values and browser support before you rely on the result.

Syntax

Call document.moveBefore. Start with this line.

JavaScript
document.moveBefore(movedNode, referenceNode)
CallWhat it does
document.moveBefore(movedNode, referenceNode)Primary signature.
document.moveBefore(...)Call with the arguments your case needs.

Built into the browser. Call moveBefore(...) on document — no import required.

Library declarations
JavaScript
document.moveBefore(movedNode, referenceNode)

Parameters

ParameterDescription
movedNodeRequired. Element or CharacterData to move
referenceNodeRequired. Insert before this Document child; null = end

Return Value

Return ValueDescription
*undefined

JavaScript Examples

Example 1 — Feature-Detect First

Limited availability means you must check before calling.

JavaScript
if (typeof document.moveBefore === "function") {
  console.log("document.moveBefore is available");
} else {
  console.log("missing — use insertBefore() or Element.moveBefore()");
}
Try It Yourself

How It Works

  1. Test for a function. Avoids a TypeError on Safari and older engines.
  2. Branch. Supported → you may call the API; missing → plan a fallback.
  3. UI tip. Everyday moves usually belong on Element.moveBefore, not Document.
  4. Baseline path. insertBefore() still works everywhere you care about.

Example 2 — MDN: Move a Comment to the End

Find a comment in body, then move it with referenceNode = null.

JavaScript
let commentNode;
for (const node of document.body.childNodes) {
  if (node.nodeType === 8) {
    commentNode = node;
    break;
  }
}

if (typeof document.moveBefore === "function" && commentNode) {
  document.moveBefore(commentNode, null);
  console.log(commentNode.parentNode === document); // true
  console.log(document.lastChild === commentNode);  // true
}
Try It Yourself

How It Works

  1. Scan body.childNodes. Comments are not elements; use nodeType === 8.
  2. Call with null. MDN: insert as the last Document child.
  3. Check ownership. parentNode becomes document.
  4. Inspect in DevTools. The comment often appears after the <html> element.

Example 3 — Fallback to insertBefore()

Use moveBefore when present; otherwise the classic Document insert API.

JavaScript
function moveUnderDocument(movedNode, referenceNode) {
  if (typeof document.moveBefore === "function") {
    document.moveBefore(movedNode, referenceNode);
    return "moveBefore";
  }
  document.insertBefore(movedNode, referenceNode);
  return "insertBefore";
}

const comment = document.createComment("demo");
document.body.appendChild(comment);
console.log(moveUnderDocument(comment, null));
// "moveBefore" or "insertBefore"
Try It Yourself

How It Works

  1. Prefer the new API. When present, you keep state-preserving moves.
  2. Fall back safely. insertBefore is Baseline and widely understood.
  3. Pass a real node. Create a comment, then move it under Document with null.
  4. Constraints. Same-document / connectedness rules still apply to moveBefore (MDN).
Compatibility

Browser Support

Document.moveBefore() is Limited availability on MDN (not Baseline). Support includes recent Chromium and Firefox; Safari currently lacks support. See the MDN moveBefore() reference.

✓ Limited availability

Document.moveBefore()

State-preserving move under the Document node. Feature-detect and fall back to insertBefore().

Limited Not Baseline
Google Chrome 133+
Yes
Microsoft Edge 133+
Yes
Mozilla Firefox 144+
Yes
Opera 118+
Yes
Apple Safari Not supported
No
Internet Explorer Not supported
No
moveBefore() Partial

Bottom line: Use document.moveBefore for rare Document-level moves. For UI, prefer Element.moveBefore with an insertBefore fallback.

Frequently Asked Questions

It moves a Node to become a direct child of the Document, before a given reference node. Unlike insertBefore(), it does not remove and reinsert the node, so state such as focus and animations can be preserved (MDN).
No. MDN does not mark Document.moveBefore() as Deprecated, Experimental, or Non-standard. It is Limited availability (not Baseline) because some major browsers do not support it yet.
None (undefined) (MDN).
If referenceNode is null, movedNode is inserted at the end of the Document's child nodes (MDN).
MDN notes it is not particularly useful on Document itself. For moving elements between containers while keeping focus or animations, prefer Element.moveBefore() (or DocumentFragment.moveBefore()).
When movedNode is not part of this document, is not Element/CharacterData, you try to move before the doctype, or connectedness constraints fail. Use insertBefore() or try/catch when those cases matter (MDN).

Next: mozSetImageElement()

Learn the Firefox-only Document method for CSS element() image sources.

mozSetImageElement() tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

AWS Certified Developer – Associate (Credly)

12 people found this page helpful

JavaScript Document importNode() Method JavaScript Document mozSetImageElement() Method