HTMLOptionElement.label — Eigenschaft · JavaScript-Referenz

Signatur

HTMLOptionElement.label

Beschreibung

Die Eigenschaft label eines HTMLOptionElement gibt an, welcher Text für eine Option angezeigt wird: in einem <select>-Element oder als Vorschlag in einem <datalist>-Element. Sie spiegelt das HTML-Attribut label wider.

Beim Lesen gibt es zwei Fälle:

Ist ein label-Attribut vorhanden, liefert die Eigenschaft dessen Wert.
Fehlt das Attribut, liefert sie den Wert von option.text. Das ist der Textinhalt der Option, wobei Leerraum am Anfang und Ende entfernt und mehrfacher Leerraum zu einem Leerzeichen zusammengefasst wird.

Deshalb bekommt man über label in der Praxis immer den sichtbaren Text, egal wie das Markup aussieht.

Beim Schreiben wird das label-Attribut gesetzt. Der Textinhalt der Option bleibt dabei unverändert. Das ist praktisch, wenn der angezeigte Text vom Inhalt der Option abweichen soll, etwa bei einer kurzen Beschriftung, bei lokalisierten Texten oder wenn in einer <datalist> zusätzlich zum Wert eine Beschreibung erscheinen soll.

Unterscheide label von value: value wird mit dem Formular übertragen, label ist nur der Text, den der Nutzer sieht.

Rückgabewert

Typ

string

Beschreibung

Der Wert des label-Attributs oder, wenn es fehlt, der Text der Option (wie bei option.text). Beim Zuweisen wird der String in das label-Attribut geschrieben.

Beispiele

Label lesen – mit und ohne Attribut

// <select id="land">
//   <option value="de" label="DE">Deutschland</option>
//   <option value="at">  Österreich  </option>
// </select>
const [de, at] = document.querySelector('#land').options;

console.log(de.label); // Wert des Attributs
console.log(at.label); // kein Attribut: Text ohne Leerraum am Rand
console.log(at.getAttribute('label'));

DE Österreich null

Beschriftung der ausgewählten Option anzeigen

const select = document.querySelector('#groesse');
const anzeige = document.querySelector('#auswahl-info');

select.addEventListener('change', () => {
  const option = select.selectedOptions[0];
  // value geht an den Server, label sieht der Nutzer
  anzeige.textContent = `Gewählt: ${option.label} (Code: ${option.value})`;
});

Gewählt: Mittel (Code: M)

Label setzen, ohne den Inhalt zu ändern

const option = new Option('Vereinigte Staaten von Amerika', 'us');
document.querySelector('#land').add(option);

// Kurze Anzeige, der Textinhalt bleibt erhalten
option.label = 'USA';

console.log(option.label);
console.log(option.text);
console.log(option.outerHTML);

USA Vereinigte Staaten von Amerika <option value="us" label="USA">Vereinigte Staaten von Amerika</option>

Beschreibungen in einer datalist

// <input list="farben"> <datalist id="farben"></datalist>
const farben = [
  { value: '#ff0000', label: 'Rot' },
  { value: '#00ff00', label: 'Grün' },
  { value: '#0000ff', label: 'Blau' }
];

const datalist = document.querySelector('#farben');
for (const { value, label } of farben) {
  const option = document.createElement('option');
  option.value = value;
  option.label = label; // erscheint zusätzlich zum Wert als Vorschlagstext
  datalist.append(option);
}

console.log([...datalist.options].map(o => o.label).join(', '));

Rot, Grün, Blau

// Wichtig · Fallstricke

Leeres Attribut: Laut Spezifikation darf label="" nicht leer sein. Ist es trotzdem leer, gibt der Getter "" zurück, und die Browser zeigen dann uneinheitlich entweder den Textinhalt oder gar nichts an. Um zum Textinhalt zurückzukehren, entferne das Attribut mit option.removeAttribute('label'), statt einen leeren String zuzuweisen.
Leerraum: Ohne Attribut wird der Text wie bei option.text bereinigt. option.textContent liefert dagegen den Rohtext mit allen Leerzeichen und Zeilenumbrüchen.
Nicht mit value verwechseln: Fehlt das value-Attribut, verwendet value ebenfalls den Text. Ein gesetztes label beeinflusst value aber nie.
Anzeige in <datalist>: Wie Wert und Beschriftung in der Vorschlagsliste dargestellt werden, hängt vom Browser ab. Manche zeigen beides an, manche nur eins davon. Verlasse dich also nicht auf eine bestimmte Darstellung.
<optgroup label>: Das ist eine eigene Eigenschaft (HTMLOptGroupElement.label) mit ähnlicher Bedeutung, aber ohne Rückgriff auf den Textinhalt.
Kompatibilität: Die Eigenschaft wird von allen aktuellen Browsern unterstützt. Das Zurückgreifen auf den Text bei fehlendem Attribut funktioniert in Firefox erst seit Version 50 zuverlässig.

Siehe auch

HTMLOptionElement.index HTMLOptionElement.value HTMLOptionElement.disabled HTMLOptionElement.form HTMLOptionElement.text