JavaScript Document getElementsByName() Method

What You’ll Learn

document.getElementsByName() is an instance method that returns every element with a given name attribute (see MDN Document: getElementsByName()). Learn the live NodeList, form and radio-group patterns, how it differs from id/class lookups, and five try-it labs.

Introduction

HTML forms often reuse the same name — radio buttons, checkboxes, or hidden fields that travel together on submit. When you need every element that shares that name, call document.getElementsByName().

MDN: the method returns a NodeList collection of elements with a given name attribute in the document. The list is live: it updates as matching elements are added or removed.

Related tutorials: getElementsByClassName(), getElementById(), getElementsByTagName().

Understanding document.getElementsByName()

An instance method on the Document object (MDN). Unlike class lookup, it is typically called on document only.

• name — the value of the name attribute to match (MDN).
• Return value — a live NodeList collection (MDN).
• Live updates — new or removed matching elements refresh the list (MDN).
• Shared names OK — radios and fields often share one name on purpose.
• Not unique — for one unique id, use getElementById().
• HTML context — name applies in (X)HTML documents (MDN).

📝 Syntax

General form of Document.getElementsByName (MDN):

getElementsByName(name)

Parameters

• name — the value of the name attribute of the element(s) we are looking for (MDN).

Return value

A live NodeList collection — it automatically updates as new elements with the same name are added to, or removed from, the document (MDN).

MDN quick sample

const upNames = document.getElementsByName("up");
console.log(upNames[0].tagName); // "INPUT"

⚖️ getElementsByName vs id / class lookups

Examples Gallery

Examples follow MDN Document: getElementsByName() and practical form patterns.

const upNames = document.getElementsByName("up");
console.log(upNames.length);
console.log(upNames[0].tagName); // "INPUT"

1
INPUT

const colors = document.getElementsByName("color");
console.log(colors.length); // 3

for (const radio of colors) {
  if (radio.checked) {
    console.log("selected:", radio.value);
  }
}

3
selected: blue
(depends on which radio is checked)

const fields = document.getElementsByName("email");
const values = Array.from(fields).map((el) => el.value);
console.log(values);

["a@example.com"]
(array of current values)

const list = document.getElementsByName("item");
console.log("before:", list.length);

const extra = document.createElement("input");
extra.name = "item";
document.body.appendChild(extra);

console.log("after:", list.length); // live list grew (MDN)

before: 1
after: 2

// <input id="user-email" name="email">
const byId = document.getElementById("user-email");
const byName = document.getElementsByName("email");

console.log(byId === byName[0]); // often true for a single field
console.log(byName.length);      // could be > 1 if name is reused

true
1

🚀 Common Use Cases

• Radio groups — find every option sharing one name.
• Form helpers — read or clear related fields in one pass.
• Hidden inputs — MDN-style lookups for named hidden controls.
• Validation — check that at least one radio in a group is selected.
• Prefer querySelectorAll — for static snapshots or richer CSS filters.
• Not unique ids — use getElementById() for one id.

📝 Notes

• MDN: Baseline Widely available since January 2018.
• MDN: returns a live NodeList.
• MDN: name can only be applied in (X)HTML documents.
• MDN: the list may include meta, object, and elements that do not formally support name.
• Shared names are normal for form controls; unique ids are for getElementById.
• Related: getElementsByClassName(), getElementById(), getElementsByTagName().

💡 Best Practices