JavaScript NamedNodeMap setNamedItem() Method

What You’ll Learn

The setNamedItem() method of a NamedNodeMap inserts or replaces an Attr node by name. Learn the MDN move-class example, what the return value means, the InUseAttributeError when an Attr is still attached elsewhere, and how it compares with setAttributeNode()—with five examples and try-it labs.

Introduction

getNamedItem() reads attributes; removeNamedItem() deletes them. setNamedItem() is how you add or update an Attr on element.attributes.

MDN’s classic demo removes class from a <span> and moves it onto a <pre> with pre.attributes.setNamedItem(classAttribute)—then shows what happens when you try to set an Attr that is still on another element.

Understanding the setNamedItem() Method

An instance method on NamedNodeMap that puts an Attr into the map, keyed by its name.

• attr — the Attr node to insert (from createAttribute, removeNamedItem, etc.).
• Returns — the replaced Attr if a same-name attribute existed, or null if the name is new.
• Replace rule — same name in the map → old Attr is replaced.
• Exception — thrown if the Attr is still part of another map (MDN).
• Common source — element.attributes.setNamedItem(attr).
• Baseline Widely available on MDN (since July 2015).

📝 Syntax

Call the method on a NamedNodeMap (usually from element.attributes):

namedNodeMap.setNamedItem(attr)

Parameters

• attr — an Attr node to add or replace in the map.

Return value

The old Attr if replaced, or null when the name is new.

Exceptions

Thrown if the attribute is still part of another map (e.g. still on a different element).

Typical pattern (MDN idea)

const span = document.querySelector("span");
const pre = document.querySelector("pre");

const classAttribute = span.attributes.removeNamedItem("class");
pre.attributes.setNamedItem(classAttribute);

console.log(pre.className); // "foo" — class moved from span to pre

⚖️ setNamedItem() vs Related Ideas

Examples Gallery

Examples follow MDN NamedNodeMap.setNamedItem. Labs use live element.attributes on real DOM nodes.

const span = document.querySelector("span");
const pre = document.querySelector("pre");

let result = `The <pre> element initially contains ${pre.attributes.length} attributes.\n\n`;
result += "We remove `class` from <span> and add it to <pre>.\n";

const classAttribute = span.attributes.removeNamedItem("class");
pre.attributes.setNamedItem(classAttribute);

result += `The <pre> element now contains ${pre.attributes.length} attributes.`;
console.log(result);

The <pre> element initially contains 1 attributes.

We remove `class` from <span> and add it to <pre>.
The <pre> element now contains 2 attributes.

const box = document.querySelector("#demo");
const map = box.attributes;

const newClass = document.createAttribute("class");
newClass.value = "updated";

const old = map.setNamedItem(newClass);

console.log(old?.value, box.className);

card updated

const box = document.querySelector("#demo");
const role = document.createAttribute("data-role");
role.value = "panel";

const replaced = box.attributes.setNamedItem(role);

console.log(replaced === null, box.getAttribute("data-role"));

true panel

const span = document.querySelector("span");
const pre = document.querySelector("pre");

const id = span.attributes.getNamedItem("id");

try {
  pre.attributes.setNamedItem(id);
} catch (error) {
  console.log(error.name);
}

InUseAttributeError

const a = document.querySelector("#box-a");
const b = document.querySelector("#box-b");

const attr = document.createAttribute("title");
attr.value = "Hello";

const viaMap = a.attributes.setNamedItem(attr);
const viaElement = b.setAttributeNode(document.createAttribute("title"));

console.log(viaMap === null, typeof viaElement);

true object

🚀 Common Use Cases

• Move attributes between elements (MDN class demo).
• Insert Attr nodes created with document.createAttribute().
• Replace an existing attribute while keeping the old Attr reference.
• Teach low-level DOM attribute mutation vs string APIs.
• Interop with legacy code that works on NamedNodeMap directly.

🔧 How It Works

📝 Notes

• MDN: Baseline Widely available (since July 2015) — no Deprecated / Experimental / Non-standard banner.
• Attr must be detached before moving—use removeNamedItem first.
• Same name → replace and return old Attr; new name → return null.
• Prefer setAttribute() for simple string updates on HTML.
• Related learning: removeNamedItem(), setAttributeNode(), getNamedItem(), Element.attributes.

💡 Best Practices