List Box Item

Option in der Listbox von Select und Combobox – Zustände und Inhalte

Ein List Box Item ist eine einzelne Option in der Listbox eines Select oder einer Combobox. Nutzer können es hervorheben und auswählen. Außerdem zeigt es Hinweise in der Listbox an, etwa wenn keine Optionen vorhanden sind oder sie nicht geladen werden konnten.

Wann verwenden

Als Option in der Listbox eines Select oder einer Combobox
Als Hinweis anstelle der Optionen: leer, wird geladen, Ladefehler (siehe content)

Wann nicht verwenden

Situation	Stattdessen
Einträge in Listen außerhalb einer Listbox, z. B. Navigation oder Inhaltslisten	List Item (eigene Komponente)
Auswahl, bei der alle Optionen dauerhaft sichtbar sein sollen	Radio Group oder Checkbox Group

Anatomie

Icon (optional): kennzeichnet die Option, z. B. ihre Kategorie. Hilft beim Überfliegen langer Listen.
Label (Pflicht): Name der Option
Subtext (optional): Zusatzinformation, um ähnliche Optionen zu unterscheiden
Auswahlfläche (Pflicht): das gesamte Item. Nicht nur Text oder Checkbox sind klickbar.

Bei multiple: true steht zusätzlich eine Checkbox vor dem Label.

Varianten

Eigenschaft	Werte	Standard	Wofür
`multiple`	`false` · `true`	`false`	`true` zeigt eine Checkbox für die Mehrfachauswahl. Begriff nach HTML `multiple`. Wird vom übergeordneten Select bzw. der Combobox übernommen.
`content`	`option` · `empty` · `busy` · `loadError`	`option`	Was das Item darstellt: eine Option oder einen Hinweis anstelle der Optionen, siehe Grenzfälle

Optionen

Option	Standard	Wirkung	Figma-Name
`hasIcon`	`false`	zeigt ein Icon vor dem Label	Icon
`hasSubtext`	`false`	zeigt einen Subtext unter dem Label	Subtext

Zustände

Achse	Werte	Hinweise
`interaction`	`none` · `hover` · `highlighted` · `focusVisible` · `active`	`highlighted`: per Tastatur hervorgehoben, siehe Glossar unten
`availability`	`enabled` · `disabled`	`disabled`: nicht auswählbar
`selected`	`false` · `true`	ARIA `aria-selected`. Wird nie nur über Farbe gezeigt, sondern zusätzlich über eine Seitenlinie (Einfachauswahl) oder eine Checkbox (Mehrfachauswahl).

highlighted (DS-eigen): Die Option ist per Pfeiltasten hervorgehoben, während der Fokus im Feld bleibt. Technisch entspricht das ARIA aria-activedescendant. Mit Enter oder Leertaste wird die hervorgehobene Option ausgewählt.

Kombinationen

Kombination	Gestaltet?	Hinweis
`highlighted` + `selected`	ja	Hervorhebung und Auswahl sind gleichzeitig erkennbar
`hover` + `selected`	ja
`disabled` + `hover` / `active`	nein	`disabled` ersetzt alle Interaktionszustände
`content: empty` / `busy` / `loadError` + jeder Zustand	nein	Hinweise sind keine Optionen und nicht interaktiv

hover, highlighted, selected und disabled müssen visuell klar voneinander unterscheidbar sein.

Verhalten

Das ganze Item ist interaktiv, nicht nur der Text oder die Checkbox.
Einfachauswahl (multiple: false): Klick auf ein Item oder Enter/Leertaste auf dem hervorgehobenen Item wählt es aus und schließt die Listbox. Eine Auswahl wird nur aufgehoben, wenn ein anderes Item gewählt wird. Ein erneuter Klick auf das bereits ausgewählte Item lässt es ausgewählt und schließt die Listbox.
Mehrfachauswahl (multiple: true): Klick oder Enter/Leertaste schaltet die Auswahl um. Die Listbox bleibt offen.
Tastatur: Das hervorgehobene Item ist immer klar sichtbar und wird automatisch in den sichtbaren Bereich gescrollt.
Deaktivierte Items können nicht ausgewählt werden.

Inhalt & Microcopy

Label: kurz und eindeutig, z. B. der Name der Option
Subtext: liefert die unterscheidende Information, z. B. eine Kennung oder ein Datum
Hinweistexte: neutral formuliert, z. B. „Keine Inhalte vorhanden“, „Inhalte werden geladen“, „Optionen konnten nicht geladen werden“

Barrierefreiheit

Semantik: ARIA-Rolle option innerhalb von listbox. Bei Mehrfachauswahl trägt die Listbox aria-multiselectable="true".
Name: Label und Subtext werden gemeinsam vorgelesen, zusammen mit dem Auswahlzustand und der Position in der Liste (z. B. „China, 1 von 16“).
Icons: Icons, die nur das Label wiederholen, werden nicht vorgelesen. Icons mit zusätzlicher Information haben eine Textalternative und werden mit dem Label vorgelesen.
Lesereihenfolge: Icon (falls informativ), Label, Subtext
Hinweise: Items mit content: empty, busy oder loadError sind keine Optionen. Sie können weder hervorgehoben noch ausgewählt werden und werden beim Erscheinen angesagt.

Die Tastaturbedienung ist in Select und Combobox beschrieben, da der Fokus im Feld bleibt.

Grenzfälle

Edge Cases

Fall	Verhalten
Liste ist leer (`content: empty`)	Neutraler Hinweis „Keine Inhalte vorhanden“ anstelle der Optionen. Kein Fehler: keine Fehlerfarbe, kein Fehler-Icon.
Optionen laden (`content: busy`)	Ladeindikator mit „Inhalte werden geladen“ anstelle der Optionen
Optionen konnten nicht geladen werden (`content: loadError`)	Kurze Fehlermeldung mit Fehler-Icon anstelle der Optionen. Wird erst sichtbar, wenn die Listbox geöffnet wird.
Sehr ähnliche Optionen, z. B. gleiche Namen	Subtext mit unterscheidender Information, z. B. Kennung oder Datum
Nur manche Optionen haben einen Subtext	Möglichst allen Optionen der Liste einen Subtext geben

Warum loadError und nicht invalid? invalid beschreibt laut naming.md eine fehlerhafte Eingabe des Nutzers. Ein Ladefehler ist ein Systemfehler und braucht deshalb einen eigenen Begriff.

Maximalausprägung

Langer Text: Passt Label oder Subtext nicht in eine Zeile, wird er umbrochen und nie gekürzt.
Textzoom: Gilt auch bei vergrößertem Text. Sobald der Text nicht mehr in eine Zeile passt, bricht er um.
Beispiel: ein Label, das in einer schmalen Listbox auf zwei Zeilen umbricht, mit einem Subtext, der ebenfalls umbricht

Minimalausprägung

Kleinste Form: nur Label, ohne Icon und Subtext
Touch-Ziel: Höhe mind. 44 px (Wert noch zu bestätigen)

Do / Don't

✅ Do: In langen Listen jeder Option ein Icon für ihre Kategorie geben. Icons helfen beim Überfliegen und beim schnellen Finden.
✅ Do: Bei identischen Labels eine Information als Subtext zeigen, die Nutzer kennen, damit die Optionen unterscheidbar sind.
⚠️ Vermeiden: Bei identischen Labels eine interne Kennung als Subtext verwenden. Sie funktioniert, ist aber für Nutzer schwerer zuzuordnen als eine Information, die sie kennen.
❌ Don't: Bei sehr ähnlichen Optionen nur das Label zeigen. Stattdessen: einen Subtext mit unterscheidender Information ergänzen.
❌ Don't: Nur einer Option einen Subtext geben. Stattdessen: allen Optionen der Liste einen Subtext geben.
✅ Do: Einen Subtext nutzen, wenn Optionen eine Erklärung brauchen, z. B. bei Paketen wie „Basis“ und „Plus“.

Änderungsprotokoll

Version	Datum	Änderung	Autorin
–	2026-10-09	Spec erstellt	Lisa Vandenhoeck
0.1	2026-10-20	In MD-Struktur überführt, Namen an naming.md angepasst	Lisa Vandenhoeck

Doku draft · Version 0.1 · Stand 2026-10-20