Object: Element
The Element object represents an element in an HTML or XML document. Elements may have attributes associated with them. You can use the Node.attributes property to retrieve a map of all the attributes attached to the element.
This object provides several methods for handling all the available attributes, individual attribute values, or individual Attr objects.
Element properties
Element methods
Method name |
Description |
Availability |
|---|---|---|
Retrieves the value of the attribute of the given name. |
4.6 or later |
|
Retrieves the attribute node of the given name. |
4.6 or later |
|
Retrieves the attribute node with the given namespace URI and local name. |
4.6 or later |
|
Retrieves the value of the attribute with the given namespace URI and local name. |
4.6 or later |
|
Returns a NodeList object that contains an array of an element’s descendent element nodes with the specified tag name. |
4.6 or later |
|
Returns a NodeList object that contains an array of an element’s descendent element nodes with the given local name and namespace URI. |
4.6 or later |
|
Determines whether an attribute of the given name is specified on the element. |
4.6 or later |
|
Determines whether an attribute of the given namespace and local name is specified on the element. |
4.6 or later |
|
Removes the attribute of the given name from the element node. |
4.6 or later |
|
Removes the specified attribute node from the element node. |
4.6 or later |
|
Removes the attribute node with the given namespace URI and local name from the element node. |
4.6 or later |
|
Adds a new attribute to an element, and sets it to the given value. |
4.6 or later |
|
Adds a new attribute node to an element. |
4.6 or later |
|
Adds a new attribute node to an element. |
4.6 or later |
|
Adds a new attribute to an element, and sets it to the given value. |
4.6 or later |
Method: Element.getAttribute()
The getAttribute() method retrieves the value of the Attr with the given name.
Return values
Returns the Node.nodeValue property of the Attr object as a string, or the empty string if that attribute has no specified or default value.
Method: Element.getAttributeNode()
The getAttributeNode() method retrieves the attribute node of the given name.
Unlike Element.getAttribute(), this method allows you to access the Attr object without having to iterate over the Node.attributes property.
Return values
Returns the Attr object with a Node.nodeName property of name, or a value of null the specified attribute doesn’t exist.
Method: Element.getAttributeNodeNS()
The getAttributeNodeNS() method retrieves the Attr node with the given namespace URI and local name.
Parameters
Parameter |
Type |
Description |
|---|---|---|
namespaceURI |
String |
The namespace of the attribute to retrieve. Specifying a value of null makes this method functionally equivalent to Element.getAttributeNode(). |
localName |
String |
The local name of the attribute to retrieve. |
Return values
Returns the Attr object with the given namespace URL and local name, or a value of null the specified attribute doesn’t exist.
Method: Element.getAttributeNS()
The getAttributeNS() method retrieves the value of the Attr with the given namespace URI and local name.
Parameters
Parameter |
Type |
Description |
|---|---|---|
namespaceURI |
String |
The namespace of the attribute for which to retrieve the value. Specifying a value of null makes this method functionally equivalent to Element.getAttribute(). |
localName |
String |
The local name of the attribute for which to retrieve the value. |
Return values
Returns the Node.nodeValue property of the Attr object as a string, or the empty string if that attribute has no specified or default value.
Method: Element.getElementsByTagName()
The getElementsByTagName() method returns a NodeList object that contains an array of an element’s descendent Element nodes with the specified tag name.
This method is identical to Document.getElementsByTagName(), except that it allows you to search a smaller subset of Element nodes.
Method: Element.getElementsByTagNameNS()
The getElementsByTagNameNS() method returns a NodeList object that contains an array of an element’s descendent Element nodes with the given local name and namespace URI.
This method is identical to Document.getElementsByTagNameNS(), except that it allows you to search a smaller subset of Element nodes.
Parameters
Parameter |
Type |
Description |
|---|---|---|
namespaceURI |
String |
The namespace of the elements to match on. Specify a value of “*” to match all elements. Specifying a value of null makes this method functionally equivalent to Element.getElementsByTagName(). |
localName |
String |
The local name of the elements to match on (that is, the qualified name minus the prefix). Specify a value of “*” to match all local elements. |
Return values
Returns a new NodeList object containing an array of all the elements with a given local name and namespace URI, in the order in which they are encountered in a preorder traversal of the Document tree.
Method: Element.hasAttribute()
Method: Element.hasAttributeNS()
Method: Element.removeAttribute()
The removeAttribute() method removes the Attr node of the given name from the element node.
If you are removing an attribute from the Element object that is known to have a default value, the attribute will immediately be reattached to the element with its default value, as well as its corresponding namespace URI, local name, and prefix, if applicable.
If the attribute has no specified or default value, this method has no effect.
Exceptions
Exception |
Description |
|---|---|
NO_MODIFICATION_ALLOWED_ERR |
This error is thrown if the Element node is read only. |
NOT_FOUND_ERR |
This error is thrown if no node exists in the Element with a Node.nodeName value of name. |
Method: Element.removeAttributeNode()
The removeAttributeNode() method removes the specified Attr node from the element node.
If you are removing an attribute from the Element object that is known to have a default value, the attribute will immediately be reattached to the element with its default value, as well as its corresponding namespace URI, local name, and prefix, if applicable.
Method: Element.removeAttributeNS()
The removeAttributeNS() method removes the Attr node with the given namespace URI and local name from the element node.
If you are removing an attribute from the Element object that is known to have a default value, the attribute will immediately be reattached to the element with its default value, as well as its corresponding namespace URI, local name, and prefix, if applicable.
If the attribute has no specified or default value, this method has no effect.
Method: Element.setAttribute()
The setAttribute() method adds a new Attr node to an element, and sets it to the given value. If an attribute with the given name already exists on the Element node, its value is changed to the given value.
This method only sets values as text strings, not entities. If the value contains any markup syntax (for example, if the value is an EntityReference), it will not be parsed and it must be properly escaped. If you want to assign values containing entities, you should use Element.setAttributeNode() or Element.setAttributeNodeNS().
Method: Element.setAttributeNode()
The setAttributeNode() method adds a new Attr node to an element. If an attribute node with the same name as the new Attr node already exists on an element, that Attr node is replaced.
Unlike Element.setAttribute(), this method allows you to add DOM nodes, instead of specifying separate arguments for the attribute name and value. Note that your attribute nodes cannot be reused in multiple elements; you must either clone the Attr node, or remove an Attr node from another element before adding it to a new element.
Return values
If newAttr replaces an existing attribute, this method returns the replaced Attr object; otherwise it returns null.
Exceptions
Exception |
Description |
|---|---|
INUSE_ATTRIBUTE_ERR |
This error is thrown if newAttr is already an attribute of another Element object. To add an attribute used elsewhere, you must clone it, and then add it. |
NO_MODIFICATION_ALLOWED_ERR |
This error is thrown if the Element object is read only. |
WRONG_DOCUMENT_ERR |
This error is thrown if newAttr was created from a different document than the one that created this Element object. |
Method: Element.setAttributeNodeNS()
The setAttributeNodeNS() method adds a new Attr node to an element. If an Attr node with the same namespace and local name as the new Attr node already exists on an element, that attribute node is replaced.
Unlike Element.setAttributeNS(), this method allows you to add DOM nodes, instead of specifying separate arguments for the attribute name and value. Note that your attribute nodes cannot be reused in multiple elements; you must either clone the Attr node, or remove an Attr node from another element before adding it to a new element.
Return values
If newAttr replaces an existing attribute, this method returns the replaced Attr object; otherwise it returns null.
Exceptions
Exception |
Description |
|---|---|
INUSE_ATTRIBUTE_ERR |
This error is thrown if newAttr is already an attribute of another Element object. To add an attribute used elsewhere, you must clone it, and then add it. |
NO_MODIFICATION_ALLOWED_ERR |
This error is thrown if the Element object is read only. |
NOT_SUPPORTED_ERR |
This error is thrown if the document does not support XML namespaces. |
WRONG_DOCUMENT_ERR |
This error is thrown if newAttr was created from a different document than the one that created this Element object. |
Method: setAttributeNS()
The setAttributeNS() method adds a new Attr node to an element, and sets it to the given value. If an attribute with the given namespace and local name already exists on the Element node, its prefix is change to the prefix portion of the qualified name, and its value is changed to the given value.
This method only sets values as text strings, not entities. If the value contains any markup syntax (for example, if the value is an EntityReference), it will not be parsed and it must be properly escaped. If you want to assign values containing entities, you should use Element.setAttributeNode() or Element.setAttributeNodeNS().
Return values
Returns the Node.nodeValue property of the Attr object as a string, or the empty string if that attribute has no specified or default value.