Document.getElementsByName() — Methode · JavaScript-Referenz

Signatur

Document.prototype.getElementsByName(name)

Beschreibung

Mit document.getElementsByName() findet man alle Elemente, deren name-Attribut einem bestimmten Wert entspricht. Das kommt vor allem bei Formularen vor: Radiobuttons einer Gruppe, gleichnamige Checkboxen oder <meta name="…">-Tags haben denselben name. Der Vergleich beachtet Groß- und Kleinschreibung und muss exakt passen.

Zurückgegeben wird eine live NodeList. Sie ändert sich also automatisch mit, wenn später Elemente mit diesem Namen ins DOM eingefügt oder daraus entfernt werden. Die NodeList kennt forEach(), length und item(), aber kein map() oder filter(). Dafür wandelt man sie erst mit Array.from() oder dem Spread-Operator in ein Array um.

Die Methode gibt es nur auf document, nicht auf einzelnen Elementen. Wer nur innerhalb eines Formulars oder Containers suchen will, nimmt form.elements.namedItem(name) oder container.querySelectorAll('[name="…"]').

Parameter

Name	Typ	Default	Beschreibung
$name Pflicht	string		Wert des `name`-Attributs, nach dem gesucht wird. Groß- und Kleinschreibung werden unterschieden. Andere Typen werden in einen String umgewandelt.

Rückgabewert

Typ

NodeList

Beschreibung

Eine live NodeList mit allen passenden Elementen in Dokumentreihenfolge. Gibt es keinen Treffer, ist sie leer (length === 0). Die Methode gibt nie null zurück.

Beispiele

Ausgewählten Radiobutton einer Gruppe ermitteln

// HTML:
// <input type="radio" name="versand" value="standard" checked>
// <input type="radio" name="versand" value="express">

const getVersandart = () => {
  const radios = document.getElementsByName('versand');
  const gewaehlt = Array.from(radios).find((r) => r.checked);
  return gewaehlt ? gewaehlt.value : null;
};

console.log(getVersandart());

standard

Alle Checkboxen einer Gruppe auswerten

// HTML: mehrere <input type="checkbox" name="interessen" value="…">
const ausgewaehlteInteressen = [...document.getElementsByName('interessen')]
  .filter((cb) => cb.checked)
  .map((cb) => cb.value);

console.log(ausgewaehlteInteressen);

["javascript", "css"]

Meta-Tag auslesen

// HTML: <meta name="description" content="Referenz für Webentwickler">
const [meta] = document.getElementsByName('description');
console.log(meta?.content ?? 'keine Beschreibung');

Referenz für Webentwickler

Live-Verhalten der NodeList

const felder = document.getElementsByName('tag');
console.log(felder.length); // 0

const input = document.createElement('input');
input.name = 'tag';
document.body.append(input);

// Dieselbe NodeList enthält jetzt das neue Element
console.log(felder.length);

0 1

// Wichtig · Fallstricke

Live-Sammlung: Wer in einer Schleife über die Liste gleichzeitig Elemente entfernt oder einfügt, bekommt unerwartete Ergebnisse. Deshalb die Liste vorher mit Array.from() kopieren.
Kein Array: map(), filter() und reduce() fehlen. forEach() ist vorhanden.
Nur auf document: element.getElementsByName gibt es nicht. Für eine begrenzte Suche nimmt man querySelectorAll('[name="…"]'), die eine statische Liste liefert. Enthält der Name Sonderzeichen, gehört er mit CSS.escape() maskiert.
Altlasten im Internet Explorer: Alte IE-Versionen fanden über diese Methode auch Elemente mit passender id und ignorierten Elemente, für die kein name-Attribut vorgesehen ist. Moderne Browser halten sich an die HTML-Spezifikation und prüfen nur das name-Attribut, bei allen HTML-Elementen.
Das name-Attribut muss nicht eindeutig sein. Wer genau ein Element eindeutig ansprechen will, nimmt besser id und getElementById().

Siehe auch

Document.getElementById() Document.getElementsByClassName() Document.getElementsByTagName() Document.querySelectorAll() NodeList HTMLFormElement.elements new WebSocketStream()