JavaScript Document getElementsByName() Method

Beginner
5 min read
Updated: Nov 2026
3 examples
Method

Definition

document.getElementsByName(name) returns a live NodeList of every element whose name attribute matches the string you pass (MDN). It is ideal for form controls that share a name, such as radio groups.

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

Syntax

Call document.getElementsByName. Start with this line.

JavaScript
document.getElementsByName(name)
CallWhat it does
document.getElementsByName(name)Primary signature.
document.getElementsByName(...)Call with the arguments your case needs.

Built into the browser. Call getElementsByName(...) on document — no import required.

Library declarations
JavaScript
document.getElementsByName(name)

Parameters

ParameterDescription
nameRequired. Value of the name attribute to match (MDN)

Return Value

Return ValueDescription
*Live NodeList

JavaScript Examples

Example 1 — Find Elements by name

MDN-style lookup: collect inputs with name="up" and read the first tag.

JavaScript
// Assume: <input type="hidden" name="up">
const upNames = document.getElementsByName("up");

console.log(upNames.length);      // 1
console.log(upNames[0].tagName);  // "INPUT"
Try It Yourself

How It Works

  1. Match the attribute. The string "up" must equal the element’s name (MDN).
  2. Get a collection. The method returns a NodeList, not a single node.
  3. Read the first item. [0] is the first match; .tagName prints INPUT.
  4. Check length. Use .length before assuming a match exists.

Example 2 — Read a Radio Group

Radios that share one name form a choice group — perfect for this API.

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

let selected = "(none)";
for (const radio of colors) {
  if (radio.checked) selected = radio.value;
}
console.log(selected); // e.g. "blue"
Try It Yourself

How It Works

  1. One name, many radios. All options use name="color".
  2. Collect the group. getElementsByName("color") returns every option.
  3. Find the choice. Loop and read .checked / .value.
  4. Why this API. Shared form names are exactly what this method is for.

Example 3 — Live NodeList Updates

Add another element with the same name and watch length grow without calling the method again.

JavaScript
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)
Try It Yourself

How It Works

  1. Store the list once. You keep a reference to the live NodeList.
  2. Add a match. A new input with name="item" enters the document.
  3. Length updates. MDN: the collection updates as matching elements are added or removed.
  4. Static alternative. querySelectorAll('[name="item"]') would stay frozen at query time.

Browser Support

Document.getElementsByName() is Baseline Widely available on MDN (since January 2018). Logos use the shared browser-image-sprite.png sprite from this project.

✓ Baseline Widely available

Document.getElementsByName()

Live NodeList of elements matching a name attribute across all major browsers.

Baseline Widely available
Google Chrome Supported
Yes
Mozilla Firefox Supported
Yes
Apple Safari Supported
Yes
Microsoft Edge Supported
Yes
Opera Supported
Yes
Internet Explorer Supported (legacy)
Yes
getElementsByName() Wide

Bottom line: Safe for form name groups today. Prefer getElementById for unique ids, or querySelectorAll for static CSS-based lookups. See the MDN Document.getElementsByName() reference.

Frequently Asked Questions

MDN: Document.getElementsByName() returns a NodeList collection of elements with a given name attribute in the document.
No. MDN marks Document.getElementsByName() as Baseline Widely available (since January 2018). It is not Deprecated, Experimental, or Non-standard.
A live NodeList collection (MDN). It automatically updates as elements with that name are added to or removed from the document.
No. id should be unique and is found with getElementById. name can be shared (for example radio buttons) and is found with getElementsByName.
MDN: the name attribute can only be applied in (X)HTML documents. The returned collection can include meta, object, and even elements that do not formally support name.
Prefer querySelectorAll('[name="..."]') when you want a static NodeList, CSS selector power, or to combine name with other filters.

Next: getElementsByTagName()

Learn how to collect every element of a given tag name into a live HTMLCollection.

getElementsByTagName() →

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.

14 people found this page helpful