setNamedItem

setNamedItem is a method defined by the DOM NamedNodeMap interface. It is used to add or replace an attribute node in a map that holds a collection of nodes, such as the attributes of an element. The method takes a single argument, a Node (typically an Attr).

If an item with the same name already exists in the map, setNamedItem replaces that node and returns the previously existing node. If there was no prior node with that name, the method returns null. This return behavior allows callers to detect whether a replacement occurred.

Error handling in typical DOM implementations includes several exceptions. If the NamedNodeMap is read-only, setNamedItem throws NO_MODIFICATION_ALLOWED_ERR. If the node provided as an argument originates from a different document, WRONG_DOCUMENT_ERR is thrown. If the node is already in use by another attribute (owner), INUSE_ATTRIBUTE_ERR may be thrown.

In practice, setNamedItem is commonly used when manipulating element attributes programmatically. It is part of a set of related operations on a NamedNodeMap, including getNamedItem, removeNamedItem, and setNamedItemNS (the namespaced variant). The latter allows setting items by namespace URI and qualified name, while setNamedItem operates on the unnamespaced name.

See also: getNamedItem, removeNamedItem, setNamedItemNS, getNamedItemNS, NamedNodeMap.