HTMLCollection.namedItem() — Methode · JavaScript-Referenz

Signatur

HTMLCollection.prototype.namedItem(name)

Beschreibung

namedItem() sucht in einer HTMLCollection nach einem Element, dessen id oder name-Attribut exakt dem übergebenen Namen entspricht. Die Elemente werden in Dokumentreihenfolge durchlaufen. Zurückgegeben wird das erste Element, bei dem die id passt oder das ein HTML-Element mit passendem name-Attribut ist. Gibt es keinen Treffer, liefert die Methode null.

Typische Anwendungsfälle sind Sammlungen wie document.forms, document.images, document.links oder element.children. Damit greift man gezielt auf ein Element zu, ohne über die Liste zu iterieren oder das ganze Dokument erneut mit querySelector() zu durchsuchen.

Der Zugriff über eckige Klammern oder Punktschreibweise (collection["login"] bzw. collection.login) ist gleichwertig, gibt bei fehlendem Treffer aber undefined statt null zurück. Außerdem kann er von Eigenschaften der Sammlung überdeckt werden, etwa bei einem Element mit id="length" oder id="item". namedItem() ist deshalb die eindeutigere Wahl.

Parameter

Name	Typ	Default	Beschreibung
$name Pflicht	string		Wert, der mit dem `id`- oder `name`-Attribut verglichen wird. Groß- und Kleinschreibung wird beachtet. Andere Werte werden in einen String umgewandelt.

Rückgabewert

Typ

Element | null

Beschreibung

Das erste passende Element in Dokumentreihenfolge oder null, wenn kein Element passt (auch bei einem leeren String).

Beispiele

Formular über document.forms finden

// HTML: <form name="login">…</form> <form id="suche">…</form>
const loginForm = document.forms.namedItem('login');
const suchForm = document.forms.namedItem('suche');

console.log(loginForm?.tagName);
console.log(suchForm?.id);
console.log(document.forms.namedItem('gibtEsNicht'));

FORM suche null

Kindelement per id aus element.children holen

// HTML: <ul id="menu"><li id="home">Start</li><li id="kontakt">Kontakt</li></ul>
const menu = document.getElementById('menu');
const kontakt = menu.children.namedItem('kontakt');

if (kontakt) {
  kontakt.classList.add('aktiv');
  console.log(kontakt.textContent);
}

Kontakt

Unterschied zu Klammer-Zugriff und überdeckte Namen

// HTML: <div id="box"><span id="length">A</span><span id="info">B</span></div>
const kids = document.getElementById('box').children;

console.log(kids.length);               // Eigenschaft der Sammlung, nicht das Element!
console.log(kids.namedItem('length').textContent);
console.log(kids['fehlt']);             // undefined
console.log(kids.namedItem('fehlt'));   // null

2 A undefined null

Live-Sammlung: späte Treffer werden gefunden

const images = document.images; // live HTMLCollection
console.log(images.namedItem('logo'));

const img = document.createElement('img');
img.id = 'logo';
document.body.append(img);

console.log(images.namedItem('logo') === img);

null true

// Wichtig · Fallstricke

Nur der erste Treffer: Haben mehrere Elemente dieselbe id oder denselben name, gibt die Methode nur das erste in Dokumentreihenfolge zurück. Für alle Treffer eignen sich querySelectorAll('[name="x"]') oder document.getElementsByName().
Unterklassen weichen ab: HTMLFormControlsCollection.namedItem() (z. B. form.elements) gibt bei mehreren gleichnamigen Steuerelementen, etwa Radiobuttons, eine RadioNodeList zurück und kein einzelnes Element.
name nur bei HTML-Elementen: Das name-Attribut zählt nur bei Elementen im HTML-Namensraum, id dagegen bei allen, also auch bei SVG-Elementen.
Groß- und Kleinschreibung: Der Vergleich beachtet sie immer, auch in HTML-Dokumenten.
Live-Sammlung: Das Ergebnis spiegelt den aktuellen Stand des DOM wider. Das ist praktisch, bei häufigem Aufruf in Schleifen aber etwas langsamer als eine einmal gespeicherte Referenz.
Ohne Argument wirft der Aufruf einen TypeError. Die Methode wird in allen Browsern unterstützt.

Siehe auch

Document.forms HTMLCollection.item() HTMLAllCollection.namedItem() HTMLAllCollection.item() HTMLSelectElement.namedItem()