Node
BaselineWidely available *
This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.
* Some parts of this feature may have varying levels of support.
TheDOMNode
interface is an abstract baseclass upon which many other DOM API objects are based, thus letting those object typesto be used similarly and often interchangeably. As an abstract class, there isno such thing as a plainNode
object. All objects that implementNode
functionality are based on one of its subclasses. Most notable areDocument
,Element
, andDocumentFragment
.
In addition, every kind of DOM node is represented by an interface based onNode
. These includeAttr
,CharacterData
(whichText
,Comment
,CDATASection
andProcessingInstruction
are all based on), andDocumentType
.
In some cases, a particular feature of the baseNode
interface may notapply to one of its child interfaces; in that case, the inheriting node mayreturnnull
or throw an exception, depending on circumstances. For example,attempting to add children to a node type that cannot have children will throw anexception.
Instance properties
In addition to the properties below,Node
inherits properties from its parent,EventTarget
.
Node.baseURI
Read onlyReturns a string representing the base URL of the documentcontaining the
Node
.Node.childNodes
Read onlyReturns a live
NodeList
containing all the children of this node(including elements, text and comments).NodeList
being live means thatif the children of theNode
change, theNodeList
object isautomatically updated.Node.firstChild
Read onlyReturns a
Node
representing the first direct child node of the node,ornull
if the node has no child.Node.isConnected
Read onlyA boolean indicating whether or not the Node is connected (directly or indirectly)to the context object, e.g., the
Document
object in the case of thenormal DOM, or theShadowRoot
in the case of a shadow DOM.Node.lastChild
Read onlyReturns a
Node
representing the last direct child node of the node,ornull
if the node has no child.Node.nextSibling
Read onlyReturns a
Node
representing the next node in the tree, ornull
if there isn't such node.Node.nodeName
Read onlyReturns a string containing the name of the
Node
. Thestructure of the name will differ with the node type. E.g. AnHTMLElement
will contain the name of the corresponding tag, like'AUDIO'
for anHTMLAudioElement
, aText
node will have the'#text'
string, or aDocument
node willhave the'#document'
string.Node.nodeType
Read onlyReturns an
unsigned short
representing the type of the node. Possiblevalues are:Name Value ELEMENT_NODE
1
ATTRIBUTE_NODE
2
TEXT_NODE
3
CDATA_SECTION_NODE
4
PROCESSING_INSTRUCTION_NODE
7
COMMENT_NODE
8
DOCUMENT_NODE
9
DOCUMENT_TYPE_NODE
10
DOCUMENT_FRAGMENT_NODE
11
Node.nodeValue
Returns / Sets the value of the current node.
Node.ownerDocument
Read onlyReturns the
Document
that this node belongs to. If the node is itselfa document, returnsnull
.Node.parentNode
Read onlyReturns a
Node
that is the parent of this node. If there is no suchnode, like if this node is the top of the tree or if doesn't participate in a tree,this property returnsnull
.Node.parentElement
Read onlyReturns an
Element
that is the parent of this node. If the node hasno parent, or if that parent is not anElement
, this property returnsnull
.Node.previousSibling
Read onlyReturns a
Node
representing the previous node in the tree, ornull
if there isn't such node.Node.textContent
Returns / Sets the textual content of an element and all its descendants.
Instance methods
In addition to the methods below,Node
inherits methods from its parent,EventTarget
.
Node.appendChild()
Adds the specified
childNode
argument as the last child to the current node.If the argument referenced an existing node on the DOM tree, the node will be detachedfrom its current position and attached at the new position.Node.cloneNode()
Clone a
Node
, and optionally, all of its contents. By default, itclones the content of the node.Node.compareDocumentPosition()
Compares the position of the current node against another node in any other document.
Node.contains()
Returns
true
orfalse
value indicating whether or not a node is adescendant of the calling node.Node.getRootNode()
Returns the context object's root which optionally includes the shadow root if it is available.
Node.hasChildNodes()
Returns a boolean value indicating whether or not the element has any child nodes.
Node.insertBefore()
Inserts a
Node
before the reference node as a child of a specifiedparent node.Node.isDefaultNamespace()
Accepts a namespace URI as an argument and returns a boolean value with avalue of
true
if the namespace is the default namespace on the given nodeorfalse
if not.Node.isEqualNode()
Returns a boolean value which indicates whether or not two nodes are of thesame type and all their defining data points match.
Node.isSameNode()
Returns a boolean value indicating whether or not the two nodes arethe same (that is, they reference the same object).
Node.lookupPrefix()
Returns a string containing the prefix for a given namespace URI,if present, and
null
if not. When multiple prefixes are possible, theresult is implementation-dependent.Node.lookupNamespaceURI()
Accepts a prefix and returns the namespace URI associated with it on the given nodeif found (and
null
if not). Supplyingnull
for the prefixwill return the default namespace.Node.normalize()
Clean up all the text nodes under this element (merge adjacent, remove empty).
Node.removeChild()
Removes a child node from the current element, which must be a child of the currentnode.
Node.replaceChild()
Replaces one child
Node
of the current one with the second one givenin parameter.
Events
selectstart
Fires when the user starts a new selection in this node.
Examples
Remove all children nested within a node
This function remove each first child of an element, until there are none left.
function removeAllChildren(element) { while (element.firstChild) { element.removeChild(element.firstChild); }}
Using this function is a single call. Here we empty the body of the document:
removeAllChildren(document.body);
An alternative could be to set the textContent to the empty string:document.body.textContent = ""
.
Recurse through child nodes
The following function recursively calls a callback function for each node contained bya root node (including the root itself):
function eachNode(rootNode, callback) { if (!callback) { const nodes = []; eachNode(rootNode, (node) => { nodes.push(node); }); return nodes; } if (callback(rootNode) === false) { return false; } if (rootNode.hasChildNodes()) { for (const node of rootNode.childNodes) { if (eachNode(node, callback) === false) { return; } } }}
The function recursively calls a function for each descendant node ofrootNode
(including the root itself).
Ifcallback
is omitted, the function returns anArray
instead, which containsrootNode
and allnodes contained within.
Ifcallback
is provided, and it returnsfalse
when called, the current recursion level is aborted, and the functionresumes execution at the last parent's level. This can be used to abort loops once anode has been found (such as searching for a text node which contains a certain string).
The function has two parameters:
rootNode
The
Node
object whose descendants will be recursed through.callback
OptionalAn optional callbackfunction thatreceives a
Node
as its only argument. If omitted,eachNode
returns anArray
of every node contained withinrootNode
(including the root itself).
The following demonstrates a real-world use of theeachNode()
function:searching for text on a web-page.
We use a wrapper function namedgrep
to do the searching:
function grep(parentNode, pattern) { let matches = []; let endScan = false; eachNode(parentNode, (node) => { if (endScan) { return false; } // Ignore anything which isn't a text node if (node.nodeType !== Node.TEXT_NODE) { return; } if (typeof pattern === "string" && node.textContent.includes(pattern)) { matches.push(node); } else if (pattern.test(node.textContent)) { if (!pattern.global) { endScan = true; matches = node; } else { matches.push(node); } } }); return matches;}
Specifications
Specification |
---|
DOM # interface-node |