Node.md

Node

The Node class is accessible as DOM.Node, not because it can be directly instantiated (trying will throw an error), but rather to give access to the static node type constants that are available on Node.

Unlike the standard DOM API, there is no separate Element class for elements. Instead, Node includes the necessary properties and methods to be able to take the place of the standard Element class, reducing complexity and code size.

Table of Contents

• Properties
  • Semi-standard
    • attributes
    • childNodes
  • Standard
    • classList
    • className
    • firstChild
    • id
    • innerHtml
    • lastChild
    • nextSibling
    • nodeName
    • nodeType
    • nodeValue
    • outerHtml
    • ownerDocument
    • parentNode
    • previousSibling
    • tagName
    • textContent
• Methods
  • Non-standard
    • forEach
  • Semi-standard
    • getRootNode
  • Standard
    • cloneNode
    • Attributes
      • getAttribute
      • getAttributeNames
      • hasAttribute
      • hasAttributes
      • removeAttribute
      • setAttribute
      • toggleAttribute
    • Children
      • appendChild
      • hasChildNodes
      • insertBefore
      • removeChild
      • replaceChild
    • Node Retrieval
      • closest
      • getElementById
      • getElementsByClassName
      • getElementsByTagName
      • matches
      • querySelector
      • querySelectorAll
• Node Type Constants

Properties

Semi-standard

• attributes Object — [standard] [MDN]

  For ELEMENT_NODE type nodes, this Object is a key/value pair of (mostly) strings that represent the names and values of each of the element's attributes. If an attribute was specified without a value, the value for the attribute in this Object will be the boolean value true. Unlike the standard, this Object is only indexable by attribute name, not by numeric index.

  For all other node types, the attributes property will not exist.

• childNodes Array — [standard] [MDN]

  An Array containing all of the children (of all node types) of this node. This property only exists on nodes of type ELEMENT_NODE, DOCUMENT_NODE, and DOCUMENT_FRAGMENT_NODE. For DOCUMENT_NODE type nodes, this Array should only ever include two nodes, the <!DOCTYPE> declaration and the document's root element.

Standard

• classList DOMTokenList or Null (read-only) — [standard] [MDN]

  Gets a DOMTokenList instance, for ELEMENT_NODE type nodes, containing the case-sensitive list of CSS class names assigned to this Node.

• className String — [standard] [MDN]

  The space separated list of CSS class names assigned to this Node.

• firstChild Node or Null (read-only) — [standard] [MDN]

  The first child node of this node, or null if this node has no children.

• id String — [standard] [MDN]

  Gets this node's id attribute, or an empty string if it either doesn't have one or this node isn't of type ELEMENT_NODE.

• innerHTML String — [standard] [MDN]

  For ELEMENT_NODE type nodes, this gets or sets the HTML markup inside this node.

• lastChild Node or Null (read-only) — [standard] [MDN]

  The last child node of this node, or null if this node has no children.

• nextSibling Node or Null (read-only) — [standard] [MDN]

  The next Node, in document order, that is a sibling to this node (ie. both nodes have the same parent node), or null if this node is the last child of its parent.

• nodeName String (read-only) — [standard] [MDN]

  Gets the name of this node, which is dependent on this node's type:

  Node Type	Value
  CDATA_SECTION_NODE	"#cdata-section"
  COMMENT_NODE	"#comment"
  DOCUMENT_FRAGMENT_NODE	"#document-fragment"
  DOCUMENT_NODE	"#document"
  DOCUMENT_TYPE_NODE	The value of this document type's name property
  ELEMENT_NODE	The value of this element's tagName property
  PROCESSING_INSTRUCTION_NODE	The value of this processing instruction's target property
  TEXT_NODE	"#text"

• nodeType Node Type [Number] (read-only) — [standard] [MDN]

  One of the node type constants that represent the type of the node.

• nodeValue String or Null — [standard] [MDN]

  This is the text content, as a String, for node types that are text-based (text nodes, comments, CDATA sections, and processing instructions). For all other node types, this property is null.

  ⚠️ Caution: For text-based nodes, setting this property to something other than a String could result in unexpected errors.

• outerHTML String — [standard] [MDN]

  For ELEMENT_NODE type nodes, this gets or sets the HTML markup that represents this node. Setting outerHTML will entirely replace this node with the result of parsing the specified string, or simply remove this node if the specified string isn't valid markup.

• ownerDocument DOM or Null (read-only) — [standard] [MDN]

  The top-level DOM object that contains this node, or null if this node is a DOM object.

• parentNode Node or Null (read-only) — [standard] [MDN]

  Gets the parent node of this node, or null if this node isn't attached as a child to any other node (ie. it was just created, or was removed).

• previousSibling Node or Null (read-only) — [standard] [MDN]

  The previous Node, in document order, that is a sibling to this node (ie. both nodes have the same parent node), or null if this node is the first child of its parent.

• tagName String or Null (read-only) — [standard] [MDN]

  For ELEMENT_NODE type nodes, this gets the tag name of this node in upper case.

• textContent String — [standard] [MDN]

  Gets the text content of this node and all of its child nodes, in document order, as a single String (excluding CDATA sections, comments, and processing instructions). Setting textContent will replace any child nodes of this node with the specified string as a new Node of type TEXT_NODE, or set the nodeValue to the specified string for text-based nodes.

Methods

Non-standard

node.forEach( callback[, type] )

Executes the specified callback function for each Node that is a descendent of this node, in document order. If the callback function returns the Boolean value false, forEach() will return and no further nodes will be visited.

Parameters

• callback Function

  The function to execute on each Node, with the following arguments:

  • current Node

    The current Node being processed.

  • parent Node

    The parentNode of the current Node.

• type Node Type [Number] (optional, default: ELEMENT_NODE)

  A node type constant indicating which type of nodes to call the callback on, or null if you want to visit all nodes regardless of node type. Only one node type may be specified.

---

Semi-standard

node.getRootNode()

[standard] [MDN]

Return Value

The top most level Node that this node is a child of. This can be a DOM instance if this node is attached to a document, or it can be the same Node instance getRootNode() was called on if the node isn't attached to a document and isn't a child of another node.

---

Standard

node.cloneNode( [deep] )

[standard] [MDN]

Returns a duplicate of this node.

Parameters

• deep Boolean (optional)

  If specified as true, indicates whether all of this node's child hierarchy should also be cloned.

Return Value

The Node that was cloned from this node.

---

Attributes

Only ELEMENT_NODE type nodes can have attributes, so the below methods that work on attributes will treat all other node types as though they simply have no attributes (since they don't).

---

node.getAttribute( name )

[standard] [MDN]

Returns the value of the specified attribute.

Parameters

• name String

  The name of the attribute whose value you want to get. This string will be lower-cased if you specify the lowerAttributeCase option as true on the DOM instance this node belongs to.

Return Value

The value of the specified attribute, or null if the attribute doesn't exist. A non-null value will normally be a String, however it can also be the Boolean value true if the attribute exists, but doesn't have an explicit value (eg. the element <button disabled></button> has an attribute named "disabled" that doesn't have a explicit value).

---

node.getAttributeNames()

[standard] [MDN]

Returns an Array of the names of the attributes on this node, in the order they were created on the node.

Return Value

An Array containing the names of this node's attributes, as String values. The array will be empty if the node has no attributes.

---

node.hasAttribute( name )

[standard] [MDN]

Returns whether this node has an attribute whose name matches the specified name.

Parameters

• name String

  The name of the attribute whose existence you want to query. This string will be lower-cased if you specify the lowerAttributeCase option as true on the DOM instance this node belongs to.

Return Value

A Boolean indicating whether this node has the specified attribute.

---

node.hasAttributes()

[standard] [MDN]

Returns whether this node has any attributes.

Return Value

A Boolean indicating whether this node has any attributes.

---

node.removeAttribute( name )

[standard] [MDN]

Removes the specified attribute from this node. If the specified attribute doesn't exist, this method does nothing.

Parameters

• name String

  The name of the attribute you want to remove. This string will be lower-cased if you specify the lowerAttributeCase option as true on the DOM instance this node belongs to.

---

node.setAttribute( name, value )

[standard] [MDN]

Sets the value of the specified attribute to the specified value, updating a pre-existing attribute with the same name or creating a new attribute.

Parameters

• name String

  The name of the attribute you want to set. This string will be lower-cased if you specify the lowerAttributeCase option as true on the DOM instance this node belongs to.

• value String or Boolean

  The value to assign to the specified attribute. When value is a String or the Boolean value true, the attribute's value is set directly to value. In all other cases, value is coerced to a String and the attribute's value is set to the result of the coercion.

  A Boolean value of true is used to represent an attribute that exists, but has no explicit value. This is mostly useful when the node is output as text.

---

node.toggleAttribute( name[, force] )

[standard] [MDN]

Toggles the existence of the specified attribute (ie. the attribute is removed if it exists, otherwise it's added and set to the Boolean value true).

Parameters

• name String

  The name of the attribute you want to toggle. This string will be lower-cased if you specify the lowerAttributeCase option as true on the DOM instance this node belongs to.

• force Boolean (optional)

  If specified, indicates whether to only add the specified attribute (when force is true), or only remove the specified attribute (when force is false).

Return Value

A Boolean indicating whether the specified attribute exists after the call to toggleAtribute().

---

Children

The below methods that work on child nodes will only work on nodes that can have child nodes (nodes of type ELEMENT_NODE, DOCUMENT_NODE, and DOCUMENT_FRAGMENT_NODE). For any method that inserts a node in some fashion, if the inserted node is a document fragment (a DOCUMENT_FRAGMENT_NODE type node), all of the top-level children of the document fragment will be removed from the fragment and then inserted in place of the document fragment.

---

node.appendChild( child )

[standard] [MDN]

Adds the specified node child to the end of this node's childNodes array. If the specified node is already in a document hierarchy, it is first removed and then added to this node's children.

Parameters

• child Node

  The node to append to the end of this node's childNodes array.

Return Value

The Node that was appended, which is usually the node specified as child. If the specified node is a document fragment, the empty document fragment node will be returned.

---

node.hasChildNodes()

[standard] [MDN]

Returns whether this node has any child nodes.

Return Value

A Boolean indicating whether this node has any child nodes.

---

node.insertBefore( newChild, refChild )

[standard] [MDN]

Inserts the node newChild into this node's childNodes array before the node refChild.

Parameters

• newChild Node

  The node to be inserted.

• refChild Node or Null

  The node before which the node newChild should be inserted. If refChild is null, insertBefore() will act exactly like appendChild(). Otherwise, if refChild isn't a Node, or isn't a direct child of this node (the node insertBefore() was called on), the node newChild will not be inserted.

Return Value

The Node that was inserted, which is usually the node specified as newChild, or null if no node was inserted. If newChild is a document fragment, the empty document fragment node will be returned.

---

node.removeChild( child )

[standard] [MDN]

Removes the specified node from this node's childNodes array.

Parameters

• child Node

  The node to be removed. If the node isn't a direct child of this node (the node removeChild() was called on), the node child will not be removed.

Return Value

The Node that was removed, or null if no node was removed.

---

node.replaceChild( newChild, oldChild )

[standard] [MDN]

Replaces the node oldChild with the node newChild.

Parameters

• newChild Node

  The node to replace the node oldChild with.

• oldChild Node

  The node being replaced. If the node isn't a direct child of this node (the node replaceChild() was called on), the node oldChild will not be replaced.

Return Value

The Node that was replaced, or null if no node was replaced.

---

Node Retrieval

node.closest( selector )

[standard] [MDN]

Starting with this Node, closest() traverses the node hierarchy toward the root node looking for the first ELEMENT_NODE type node that matches the specified selector.

Parameters

• selector String

  The selector string to match against. See the selectors documentation for a list supported selectors.

Return Value

The Node that was first matched by the specified selector, or null if no node matched.

Exceptions

A SyntaxError is thrown if the specified selector is invalid. The message of the SyntaxError will have a more detailed description of what exactly the error is, and the stack property of the error object will have information about where in the selector the error was encountered.

---

node.getElementById( id )

[standard] [MDN]

Gets the first ELEMENT_NODE type node which has an id attribute that matches the specified id parameter string.

Parameters

• id String

  The id attribute of the element to locate. The comparison is case sensitive.

Return Value

The Node whose id attribute matches the specified ID, or null if no element was found.

---

node.getElementsByClassName( className )

[standard] [MDN]

Gets all ELEMENT_NODE type nodes which have a class attribute that contains the specified className parameter string and are descendents of this node.

Parameters

• className String

  One or more class names to locate, separated by whitespace. All class names must exist on an element for it to be considered matching. The comparison is case sensitive.

Return Value

An Array of all elements (that are children of the element this method was called on) whose class attribute contains the specified class name or names. The array will be empty if no elements matched.

---

node.getElementsByTagName( tagName )

[standard] [MDN]

Gets all ELEMENT_NODE type nodes which have a tagName that matches the specified tagName parameter string and are descendents of this node.

Parameters

• tagName String

  The tagName of the elements to locate. The comparison is not case sensitive.

Return Value

An Array of all elements (that are children of the element this method was called on) whose tagName matches the specified one. The array will be empty if no elements matched.

---

node.matches( selector )

[standard] [MDN]

Return whether this node would be selected by the specified selector.

Parameters

• selector String

  The selector string to match against. See the selectors documentation for a list supported selectors.

Return Value

A Boolean indicating whether this node would be selected by the specified selector.

Exceptions

A SyntaxError is thrown if the specified selector is invalid. The message of the SyntaxError will have a more detailed description of what exactly the error is, and the stack property of the error object will have information about where in the selector the error was encountered.

---

node.querySelector( selector )

[standard] [MDN]

Returns the first ELEMENT_NODE type node that matches the specified selector and is a descendent of this node.

Parameters

• selector String

  The selector string to match against. See the selectors documentation for a list supported selectors.

Return Value

The Node that was first matched by the specified selector, or null if no node matched.

Exceptions

A SyntaxError is thrown if the specified selector is invalid. The message of the SyntaxError will have a more detailed description of what exactly the error is, and the stack property of the error object will have information about where in the selector the error was encountered.

---

node.querySelectorAll( selector )

[standard] [MDN]

Gets all ELEMENT_NODE type nodes that match the specified selector and are descendents of this node.

Parameters

• selector String

  The selector string to match against. See the selectors documentation for a list supported selectors.

Return Value

An Array of all elements that match the specified selector. The array will be empty if no elements matched.

Exceptions

A SyntaxError is thrown if the specified selector is invalid. The message of the SyntaxError will have a more detailed description of what exactly the error is, and the stack property of the error object will have information about where in the selector the error was encountered.

---

Node Type Constants

Constant	Value	Description
Node.ELEMENT_NODE	1	An element node (such as <p> or <div>) that has a tagName property, along with supporting attributes and child nodes.
Node.TEXT_NODE	3	A text node that only stores plain text as a String in its nodeValue property.
Node.CDATA_SECTION_NODE	4	A CDATA section node, commonly used in XML documents to include portions of text without the need to escape the characters < and &.
Node.PROCESSING_INSTRUCTION_NODE	7	A processing instruction node, commonly used in XML documents to embed application-specific instructions. These nodes have a target property rather than the tagName property of element nodes, and do not support attributes or child nodes. Unlike browsers, all other text inside the node (other than the target) is stored in the node's nodeValue property as a String.
Node.COMMENT_NODE	8	A comment node (such as <!-- comment -->) that stores the text content of the comment in the node's nodeValue property as a String.
Node.DOCUMENT_NODE	9	A document node, created by instantiating the DOM class.
Node.DOCUMENT_TYPE_NODE	10	A document type node.
Node.DOCUMENT_FRAGMENT_NODE	11	A document fragment node, created by instantiating the DOM class without either a <!DOCTYPE> or an <html> element.