The Node.compareDocumentPosition() method reports where another node sits relative to this one. Learn the DOCUMENT_POSITION_* bitmask flags, how to test them with &, and common ancestor / order checks.
Instance method
Bitmask integer
Bitwise AND (&)
Returns 0
Precede / contain…
Baseline widely
Sometimes you need more than “is this inside that?” You may need document order: does A come before B? Is B an ancestor? compareDocumentPosition() answers with a single integer bitmask.
MDN stresses that because the result is a bitmask, you must use the bitwise AND operator (&) for meaningful checks—not === against one flag alone when multiple bits might be set.
Read the call as “where is otherNode relative to me?” So head.compareDocumentPosition(body) describes body’s position relative to head.
compareDocumentPosition()MDN: the method reports the position of its argument node relative to the node on which it is called.
Node.DOCUMENT_POSITION_* bits combined.0.PRECEDING / FOLLOWING in tree order.CONTAINS (ancestor) / CONTAINED_BY (descendant).const mask = node.compareDocumentPosition(otherNode);
if (mask & Node.DOCUMENT_POSITION_FOLLOWING) {
// otherNode follows node
}otherNode — The node whose position is reported relative to node.An integer bitmask, or 0 when otherNode is the same as this node.
| Constant | Value | Meaning (about otherNode) |
|---|---|---|
DOCUMENT_POSITION_DISCONNECTED | 1 | Different documents or different trees |
DOCUMENT_POSITION_PRECEDING | 2 | Comes before this node (tree / consistent order) |
DOCUMENT_POSITION_FOLLOWING | 4 | Comes after this node |
DOCUMENT_POSITION_CONTAINS | 8 | Is an ancestor of this node |
DOCUMENT_POSITION_CONTAINED_BY | 16 | Is a descendant of this node |
DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC | 32 | Order may be arbitrary / not portable |
Multiple bits can combine. MDN example: earlier in the document and containing this node → CONTAINS | PRECEDING → 10 (0x0A).
| Goal | Code |
|---|---|
| Does other follow me? | node.compareDocumentPosition(other) & Node.DOCUMENT_POSITION_FOLLOWING |
| Is other my ancestor? | … & Node.DOCUMENT_POSITION_CONTAINS |
| Is other my descendant? | … & Node.DOCUMENT_POSITION_CONTAINED_BY |
| Same node? | node.compareDocumentPosition(node) === 0 |
| head before body? | head.compareDocumentPosition(body) & Node.DOCUMENT_POSITION_FOLLOWING |
| MDN status | Baseline Widely available (since July 2015) |
Four facts to remember about compareDocumentPosition().
bitmask | 0Integer flags
widelySince July 2015
mask & flagNot === alone
otherNodeArg vs this
Examples follow MDN Node.compareDocumentPosition() patterns. Use View Output or Try It Yourself for each case.
MDN head/body check and the same-node zero result.
body Follow head? (MDN)Use bitwise AND to test DOCUMENT_POSITION_FOLLOWING.
const head = document.head;
const body = document.body;
if (head.compareDocumentPosition(body) & Node.DOCUMENT_POSITION_FOLLOWING) {
console.log("Well-formed document");
} else {
console.error("<head> is not before <body>");
}Relative to head, body follows in document order, so the FOLLOWING bit is set and the condition is truthy.
0Comparing a node to itself yields no position bits.
const el = document.getElementById("box");
console.log(el.compareDocumentPosition(el)); // 0MDN: the return is 0 when otherNode is the same as this node.
Ancestor/descendant checks, sibling order, and multi-flag masks.
CONTAINS vs CONTAINED_BY depend on which node you call.
const parent = document.getElementById("parent");
const child = document.getElementById("child");
const fromChild = child.compareDocumentPosition(parent);
console.log(!!(fromChild & Node.DOCUMENT_POSITION_CONTAINS));
// true — parent is an ancestor of child
const fromParent = parent.compareDocumentPosition(child);
console.log(!!(fromParent & Node.DOCUMENT_POSITION_CONTAINED_BY));
// true — child is a descendant of parentAlways interpret flags relative to the receiver. For “is A inside B?” you can also use B.contains(A) when both are Elements—this API is richer for order.
Earlier siblings set DOCUMENT_POSITION_PRECEDING.
const a = document.getElementById("a");
const b = document.getElementById("b");
const mask = b.compareDocumentPosition(a);
console.log(!!(mask & Node.DOCUMENT_POSITION_PRECEDING));
// true — a precedes b relative to bFrom b’s point of view, a comes earlier in the tree, so the PRECEDING bit is set.
An ancestor that also precedes you can set two flags at once.
const wrap = document.getElementById("wrap");
const nested = document.getElementById("nested");
const mask = nested.compareDocumentPosition(wrap);
console.log(mask);
// often 10 = CONTAINS (8) | PRECEDING (2)
console.log(!!(mask & Node.DOCUMENT_POSITION_CONTAINS));
console.log(!!(mask & Node.DOCUMENT_POSITION_PRECEDING));
console.log(mask === Node.DOCUMENT_POSITION_CONTAINS); // false — extra bits!This is why MDN insists on &. Comparing the whole mask with === to a single constant fails when other bits are also set.
Call on one node; pass the other as otherNode.
Sets PRECEDING, FOLLOWING, CONTAINS, and related bits as needed.
mask & Node.DOCUMENT_POSITION_* is truthy when that flag is set.
Reorder UI, validate structure, or branch your logic.
&; multiple bits may be set together.IMPLEMENTATION_SPECIFIC can appear with disconnected / arbitrary ordering.Node.compareDocumentPosition() is Baseline Widely available across modern browsers (MDN: since July 2015). Logos use the shared browser-image-sprite.png sprite from this project.
Safe for production. Remember bitmask & checks; same node returns 0.
Bottom line: Use & with DOCUMENT_POSITION_* flags; do not rely on === against a single flag when bits may combine.
Node.compareDocumentPosition() describes where another node sits relative to this one as a bitmask. Test with &, remember 0 for the same node, and use the DOCUMENT_POSITION_* constants for clear intent.
Continue with contains(), cloneNode(), or the JavaScript hub.
mask & Node.DOCUMENT_POSITION_*0 as “same node”mask === FOLLOWING when other bits may be setDISCONNECTED across trees/documentsNode with the Node.js runtime& because the raw number “looks right”compareDocumentPosition()Relative position as a bitmask of document flags.
integer flags
APItest each flag
Checkidentical node
Edgeancestor / child
Treee.g. 10
GotchaMDN’s classic check head.compareDocumentPosition(body) & Node.DOCUMENT_POSITION_FOLLOWING is a tiny way to confirm a well-formed document where <body> follows <head>.
Simple boolean check for descendants (inclusive of self).
5 people found this page helpful