JavaScript NamedNodeMap setNamedItem() Method

Beginner
5 min read
Updated: Nov 2026
5 examples
Method
Decorative image with the word SETNAMEDITEM

Definition

NamedNodeMap.setNamedItem(attr) puts an Attr into the map (usually element.attributes). If a same-name attribute already exists, it is replaced (MDN).

Pass the required arguments shown below. Check return values and browser support before you rely on the result.

Syntax

Call map.setNamedItem. Start with this line.

JavaScript
map.setNamedItem(attr)
CallWhat it does
map.setNamedItem(attr)Primary signature.
map.setNamedItem(...)Call with the arguments your case needs.

Built into the browser. Call setNamedItem(...) on a NamedNodeMap — no import required.

Library declarations
JavaScript
map.setNamedItem(attr)

Parameters

ParameterDescription
attrRequired. Attr node to insert

Return Value

Return ValueDescription
*Old Attr, or null if new

JavaScript Examples

Example 1 — Insert New

Setting a brand-new Attr returns null.

JavaScript
const el = document.createElement("div");
const attr = document.createAttribute("title");
attr.value = "Hello";

const old = el.attributes.setNamedItem(attr);

console.log(old);          // null
console.log(el.title);     // Hello
Try It Yourself

How It Works

  1. Create an Attr. Name it title and set a value.
  2. Set on the map. The element had no title yet.
  3. Return is null. Nothing was replaced.
  4. Readable. el.title reflects the new attribute.

Example 2 — Replace Existing

Replacing returns the previous Attr.

JavaScript
const el = document.createElement("div");
el.setAttribute("data-id", "1");

const next = document.createAttribute("data-id");
next.value = "2";

const old = el.attributes.setNamedItem(next);

console.log(old.value); // 1
console.log(el.getAttribute("data-id")); // 2
Try It Yourself

How It Works

  1. Start with a value. Element already has data-id="1".
  2. Build a replacement Attr. Same name, new value "2".
  3. Set it. The map swaps the old Attr out.
  4. Old is returned. You can still read old.value.

Example 3 — Move an Attr

Remove from one map, then set on another (MDN idea).

JavaScript
const from = document.createElement("span");
from.className = "foo";
const to = document.createElement("pre");

const cls = from.attributes.removeNamedItem("class");
to.attributes.setNamedItem(cls);

console.log(to.className);   // foo
console.log(from.className); // ""
Try It Yourself

How It Works

  1. Remove. Detach class so it is free.
  2. Set. Attach the same Attr node to to.
  3. Source cleared. from no longer has the class.
  4. Target updated. to.className is "foo".

Example 4 — InUseAttributeError

Setting an Attr that is still attached elsewhere throws.

JavaScript
const a = document.createElement("span");
a.id = "bar";
const b = document.createElement("pre");

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

try {
  b.attributes.setNamedItem(id); // still on a
} catch (e) {
  console.log(e.name); // InUseAttributeError
}
Try It Yourself

How It Works

  1. Get without remove. getNamedItem only looks up.
  2. Still owned. The Attr remains on a.
  3. Set fails. Another map cannot take it yet.
  4. Fix. Call removeNamedItem("id") first, then set.

Example 5 — createAttribute + set

Build an Attr with createAttribute, then insert it.

JavaScript
const el = document.createElement("button");
const attr = document.createAttribute("type");
attr.value = "button";

el.attributes.setNamedItem(attr);

console.log(el.type); // button
console.log(el.attributes.length);
Try It Yourself

How It Works

  1. Create. document.createAttribute("type") builds a free Attr.
  2. Assign value. Set attr.value before inserting.
  3. Set on the map. The button now has type="button".
  4. Tip. For simple cases, el.type = "button" or setAttribute is shorter.
Compatibility

Browser Support

NamedNodeMap.setNamedItem() is marked Baseline Widely available on MDN (since July 2015). DOM API — not a Node.js built-in.

✓ Baseline · Widely available

setNamedItem()

Insert or replace Attr nodes across modern browsers. Remove first when moving an Attr between elements.

98% Core tag support
Chrome 1+
Full support
Edge 12+
Full support
Firefox 1+
Full support
Safari 1+
Full support
Opera ✓
Full support
HTML element 100% supported

Bottom line: Safe for production. Use setNamedItem(attr) when working with Attr nodes; use setAttribute for simple string updates.

Frequently Asked Questions

It inserts an Attr node into the map by its name. If an attribute with the same name already exists, it is replaced. Typical use: element.attributes.setNamedItem(attr).
No. MDN marks NamedNodeMap.setNamedItem() as Baseline Widely available (since July 2015). It is not Deprecated, Experimental, or Non-standard.
The old Attr if a same-name attribute was replaced, or null if the attribute is new to the map.
InUseAttributeError (DOMException) if the Attr is still part of another map — remove it first with removeNamedItem().
setNamedItem takes an Attr node on the NamedNodeMap. element.setAttribute(name, value) takes strings and creates or updates the attribute for you.
When moving Attr nodes between elements (MDN example), or when you already have an Attr from removeNamedItem() or createAttribute(). For everyday HTML strings, setAttribute() is usually simpler.

Next: setNamedItemNS()

Same insert/replace API — the NS-named alias.

setNamedItemNS() →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

AWS Certified Developer – Associate (Credly)

8 people found this page helpful

JavaScript NamedNodeMap removeNamedItemNS() Method JavaScript NamedNodeMap setNamedItemNS() Method