HTMLButtonElement.labels — Eigenschaft · JavaScript-Referenz

Signatur

HTMLButtonElement.labels

Beschreibung

Die Eigenschaft labels eines HTMLButtonElement gibt eine NodeList mit allen <label>-Elementen zurück, die dem Button zugeordnet sind. Die Zuordnung kommt auf zwei Wegen zustande: explizit über das Attribut for des Labels, das auf die id des Buttons zeigt, oder implizit, wenn der Button innerhalb des <label>-Elements steht.

Praktisch ist die Eigenschaft, wenn man per Skript die Beschriftung eines Buttons auslesen, hervorheben oder für Barrierefreiheits-Prüfungen auswerten möchte, ohne selbst das Dokument nach passenden for-Attributen zu durchsuchen. Ein Button kann dabei mehrere Labels haben, deshalb ist das Ergebnis immer eine Liste.

Die zurückgegebene NodeList ist live: Werden Labels hinzugefügt, entfernt oder das for-Attribut geändert, spiegelt dieselbe Liste den neuen Zustand wider. Gibt es keine zugeordneten Labels, erhält man eine leere NodeList (Länge 0), nicht null.

Rückgabewert

Typ

NodeList<HTMLLabelElement>

Beschreibung

Live-NodeList mit allen zugeordneten <label>-Elementen in Dokumentreihenfolge; leer, wenn keine Labels existieren.

Beispiele

Explizite und implizite Labels auslesen

// HTML:
// <label for="senden">Formular absenden</label>
// <label>Alternativ: <button id="senden" type="submit">Los</button></label>

const button = document.getElementById('senden');
console.log(button.labels.length);

for (const label of button.labels) {
  console.log(label.textContent.trim());
}

2 Formular absenden Alternativ: Los

Labels beim Fokus des Buttons hervorheben

// HTML: <label for="speichern">Änderungen speichern</label>
//       <button id="speichern">Speichern</button>

const button = document.querySelector('#speichern');

const setHighlight = (aktiv) => {
  button.labels.forEach((label) => label.classList.toggle('aktiv', aktiv));
};

button.addEventListener('focus', () => setHighlight(true));
button.addEventListener('blur', () => setHighlight(false));

Barrierefreiheits-Check: Buttons ohne Label und ohne Text finden

const unbeschriftet = [...document.querySelectorAll('button')].filter(
  (btn) =>
    btn.labels.length === 0 &&
    !btn.textContent.trim() &&
    !btn.hasAttribute('aria-label')
);

console.log(`${unbeschriftet.length} Button(s) ohne zugängliche Beschriftung`);

z. B.: 1 Button(s) ohne zugängliche Beschriftung

Live-Verhalten der NodeList

const button = document.createElement('button');
button.id = 'dyn';
document.body.append(button);

const labels = button.labels;
console.log(labels.length); // 0

const label = document.createElement('label');
label.htmlFor = 'dyn';
label.textContent = 'Dynamisches Label';
document.body.append(label);

console.log(labels.length); // dieselbe Liste, jetzt 1

0 1

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung an button.labels wird ignoriert (im Strict Mode TypeError). Labels ordnet man über label.htmlFor bzw. das for-Attribut oder durch Verschachtelung zu.
Live-Liste: Beim Entfernen von Labels während einer Iteration kann sich die Liste verändern. Für stabile Schleifen vorher mit [...button.labels] oder Array.from() kopieren.
Nur im selben Baum: Labels werden nur gefunden, wenn sie sich im selben Dokument bzw. derselben Shadow-Root wie der Button befinden. Ein for-Attribut über Shadow-DOM-Grenzen hinweg funktioniert nicht.
Klickt man auf ein Label, wird der zugehörige Button aktiviert (löst also click aus) – bei type="submit" kann das unbeabsichtigt ein Formular absenden.
aria-labelledby-Verknüpfungen tauchen in labels nicht auf; die Eigenschaft berücksichtigt ausschließlich echte <label>-Elemente.
Kompatibilität: In allen aktuellen Browsern verfügbar; sehr alte Versionen (Internet Explorer, Firefox vor 56) kennen die Eigenschaft nicht.

Siehe auch

HTMLButtonElement.formMethod HTMLButtonElement.name HTMLButtonElement.type HTMLButtonElement.value HTMLButtonElement.disabled