Combobox

Synonyme: Auswahlliste mit Autovervollständigung, Dropdown mit Freitexteingabe, Autocomplete

Beschreibung: Die Combobox kombiniert ein Texteingabefeld mit einer Vorschlagsliste. Nutzende können einen Wert frei eingeben oder einen der angebotenen Vorschläge übernehmen. Der Wert ist dabei nicht auf die Vorschläge beschränkt.

Die Komponente basiert auf einem nativen Texteingabefeld (input type="text"), das KoliBri nach dem WAI-ARIA-Pattern „Editable Combobox with List Autocomplete“ mit einer eigenen Vorschlagsliste (Listbox) verbindet. Es wird bewusst kein natives datalist-Element verwendet; Rollen, Zustände und Tastatursteuerung setzt KoliBri selbst um.

Während der Eingabe werden die Vorschläge gefiltert. Die Filterung erfolgt über eine Substring-Suche, sodass der Suchbegriff an beliebiger Stelle eines Vorschlags vorkommen kann.

Die Komponente eignet sich insbesondere für umfangreiche Auswahllisten oder Situationen, in denen Nutzende den gesuchten Eintrag nicht vollständig kennen.

Beispiel

Standard-Combobox mit Vorschlagsliste:

<KolCombobox _label="Freie Eingabe mit Vorschlägen" _suggestions={[ "JavaScript", "Python", "SQL", "TypeScript", "Java", "C#", "C++", "C", "PHP", "Go" ]} />

Barrierefreiheit

• Das Eingabefeld muss mit einer aussagekräftigen Beschriftung versehen werden. Es darf visuell ausgeblendet werden, wenn der Zweck des Eingabefeldes durch den direkten visuellen Kontext absolut unmissverständlich ist.

• Im Fehlerfall wird die Fehlermeldung direkt an der Komponente dargestellt und automatisch mit ihr verknüpft, sodass sie auch assistiven Technologien zur Verfügung steht.

Konkrete Designentscheidungen

Entscheidung	Begründung
Die Combobox orientiert sich am WAI-ARIA APG Pattern „Editable Combobox with List Autocomplete“, weicht jedoch beim Fokusmodell bewusst davon ab.	Die Implementierung folgt den grundlegenden Interaktions- und ARIA-Konzepten des Patterns, verwendet jedoch ein angepasstes Fokusverhalten, um die Navigation innerhalb der Vorschlagsliste zu vereinfachen.
Beim Navigieren innerhalb der Vorschlagsliste wird der Tastaturfokus auf den jeweiligen Vorschlag verschoben.	Anders als im WAI-ARIA APG Pattern verbleibt der Fokus während der Listennavigation nicht im Eingabefeld. Stattdessen wechselt er auf den jeweils aktiven Vorschlag. Während der Navigation kann daher kein weiterer Suchtext eingegeben werden. Dieses Verhalten ist eine bewusste Designentscheidung der KoliBri-Combobox.
Die Vorschlagsliste wird als eigene Liste und nicht als natives datalist umgesetzt.	Native datalist-Elemente unterscheiden sich je nach Browser hinsichtlich Darstellung, Tastaturbedienung und Unterstützung durch assistive Technologien. Die eigene Umsetzung ermöglicht ein konsistentes Verhalten und Styling über alle unterstützten Plattformen hinweg.
Der Öffnen-/Schließen-Pfeil ist nicht Teil der Tab-Reihenfolge.	Er dient ausschließlich als zusätzliche Unterstützung für Maus- und Touch-Nutzende. Die gleiche Funktion steht über die Pfeiltasten im Eingabefeld zur Verfügung, sodass unnötige Tabstopps vermieden werden.
Der Suchbegriff wird in den Vorschlägen hervorgehoben (mark).	Sehende Nutzende erkennen auf einen Blick, warum ein Vorschlag zur Eingabe passt – auch wenn der Suchbegriff mitten im Vorschlag steht.

Links und Referenzen

Verwendung

• Verwenden Sie die Combobox, wenn Nutzende einen Wert frei eingeben dürfen, dabei aber durch Vorschläge unterstützt werden sollen.
• Übergeben Sie die Vorschläge über _suggestions als Liste von Zeichenketten.
• Der Wert (_value) entspricht immer dem Text im Eingabefeld und ist nicht auf die Vorschläge beschränkt. Muss genau ein vordefinierter Wert gewählt werden, verwenden Sie stattdessen SingleSelect oder Select.
• Verwenden Sie aussagekräftige Beschriftungen (_label) und setzen Sie _required, wenn eine Eingabe verpflichtend ist.

Implizites Verhalten

• Die Vorschläge werden über eine Substring-Suche ohne Beachtung der Groß-/Kleinschreibung gefiltert; führende und nachfolgende Leerzeichen werden ignoriert. Der Suchbegriff muss daher nicht am Anfang eines Vorschlags stehen, z. B. findet üssel den Vorschlag „Düsseldorf“ und berg den Vorschlag „Nürnberg“.
• Der Suchbegriff wird in den passenden Vorschlägen hervorgehoben.
• Passen Vorschläge zur Eingabe, öffnet sich die Vorschlagsliste automatisch. Passt kein Vorschlag, wird sie geschlossen.
• Entspricht die Eingabe exakt (einschließlich Groß-/Kleinschreibung) dem einzigen passenden Vorschlag, schließt sich die Vorschlagsliste automatisch.
• Ist das Eingabefeld leer, enthält die Vorschlagsliste alle Vorschläge.

Hinweis: Die Combobox prüft nicht, ob der eingegebene Wert einem Vorschlag entspricht. Die Validierung muss auf Anwendungsebene erfolgen.

Tastatursteuerung

Die Tastatursteuerung wird nicht vom Browser, sondern von KoliBri selbst umgesetzt.

Taste	Funktion
Tab	Fokus auf das Eingabefeld bzw. das nächste fokussierbare Element setzen. Eine geöffnete Liste wird dabei ohne Auswahl geschlossen.
Shift+Tab	Fokus auf das vorherige fokussierbare Element setzen. Eine geöffnete Liste wird dabei ohne Auswahl geschlossen.
Pfeil-Taste unten	Liste öffnen und Fokus auf den nächsten Eintrag setzen. Nach dem letzten Eintrag folgt wieder der erste.
Pfeil-Taste oben	Liste öffnen und Fokus auf den vorherigen Eintrag setzen. Vor dem ersten Eintrag folgt wieder der letzte.
Pos1/Ende	Bei geöffneter Liste Fokus auf den ersten/letzten Eintrag setzen.
Bild-Tasten (hoch/runter)	Bei geöffneter Liste Fokus um zehn Einträge nach oben/unten verschieben. Wird das Listenende über- bzw. der Listenanfang unterschritten, springt der Fokus zum ersten bzw. letzten Eintrag.
Enter	Ist ein Vorschlag fokussiert, wird er übernommen, die Vorschlagsliste geschlossen und der Fokus in das Eingabefeld gesetzt. Ist die Liste geschlossen, wird sie geöffnet (sofern passende Vorschläge vorhanden sind). Liegt der Fokus auf dem Clear-Button, wird die Eingabe gelöscht.
Leertaste	Ist ein Vorschlag fokussiert, wird er übernommen, die Vorschlagsliste geschlossen und der Fokus in das Eingabefeld gesetzt. Liegt der Fokus auf dem Clear-Button, wird die Eingabe gelöscht. Im Eingabefeld wird ein Leerzeichen eingegeben.
Esc	Liste ohne Auswahl schließen und Fokus in das Eingabefeld setzen. Der eingegebene Text bleibt erhalten.
Zeicheneingabe (Fokus im Eingabefeld)	Liste entsprechend der Eingabe filtern.
Buchstabe oder Ziffer (Fokus auf einem Eintrag)	Fokus auf den ersten Eintrag setzen, dessen Beschriftung mit dem eingegebenen Zeichen beginnt. Das Zeichen wird nicht in das Eingabefeld übernommen. Berücksichtigt werden nur die Buchstaben A–Z und Ziffern (keine Umlaute).

Hinweis: Pos1 und Ende bewegen auch im Eingabefeld nicht den Textcursor.

Fokusmodell

Die Komponente orientiert sich am WAI-ARIA Authoring Practices Pattern „Editable Combobox with List Autocomplete“, weicht jedoch beim Fokusmodell davon ab: Während der Navigation innerhalb der Liste (Pfeiltasten, Pos1/Ende, Bild-Tasten) wird der Tastaturfokus auf den jeweils aktiven Eintrag verschoben. Im WAI-ARIA APG Pattern verbleibt der Fokus dagegen während der gesamten Interaktion im Eingabefeld.

Dieses Fokusmodell hat folgende Auswirkungen:

• Während der Navigation innerhalb der Liste kann kein weiterer Suchtext eingegeben werden.
• Buchstaben- und Zifferneingaben bei Fokus auf einem Eintrag setzen den Fokus auf den ersten Eintrag, dessen Beschriftung mit dem eingegebenen Zeichen beginnt.
• Nach dem Schließen der Liste bzw. nach einer Auswahl wird der Fokus in das Eingabefeld gesetzt.
• Verlässt der Fokus die Komponente, wird die Liste geschlossen.

Best Practices / Empfehlungen

• Verwenden Sie die Combobox bei umfangreichen Vorschlagslisten, in denen Nutzende gezielt nach einem Eintrag suchen, aber auch eigene Werte eingeben dürfen.
• Stellen Sie nur relevante, eindeutig bezeichnete und unterscheidbare Vorschläge bereit.
• Führen Sie häufig verwendete Vorschläge möglichst am Anfang der Vorschlagsliste auf.
• Die Combobox eignet sich bei vielen thematisch ähnlichen Einträgen.
• Nutzen Sie _hint, um Formatvorgaben oder Besonderheiten der Eingabe zu erläutern.
• Da die Combobox freie Eingaben zulässt, prüfen Sie den Wert auf Anwendungsebene und melden Sie ungültige Eingaben über _msg mit einer verständlichen und konkreten Fehlermeldung zurück.
• Verwenden Sie SingleSelect oder Select, wenn ausschließlich vordefinierte Werte zulässig sind.

Anwendungsfälle

• Personensuche
• Kunden- oder Lieferantenauswahl
• Produktauswahl in umfangreichen Sortimenten
• Orts- oder Postleitzahlensuche
• Organisations- oder Behördenauswahl
• Auswahl aus umfangreichen Datensätzen
• Eingaben, bei denen neben bekannten Werten auch eigene Werte zulässig sind (z. B. Berufs- oder Funktionsbezeichnungen)

FAQ

Wann sollte ich Combobox, SingleSelect oder Select verwenden?
Die Combobox ist die einzige der drei Komponenten, die freie Eingaben zulässt. Muss genau ein vordefinierter Wert gewählt werden, eignet sich bei umfangreichen Listen ein SingleSelect (mit Filterung) und bei überschaubaren Listen ein Select.

Kriterium	Combobox	SingleSelect	Select
Freie Eingabe	ja	nein	nein
Filtern per Texteingabe	ja	ja	nein
Technische Grundlage	natives input mit ARIA-Listbox	natives input mit ARIA-Listbox	natives select

Warum wird kein natives datalist verwendet?
Die KoliBri-Combobox verwendet eine eigene ARIA-basierte Listbox, um ein konsistentes Verhalten hinsichtlich Tastatursteuerung, Styling und Unterstützung durch assistive Technologien über alle unterstützten Browser hinweg sicherzustellen.

Worin weicht die Tastatursteuerung vom WAI-ARIA APG Pattern ab?
Während der Navigation innerhalb der Vorschlagsliste wird der Tastaturfokus auf den aktiven Vorschlag verschoben, statt im Eingabefeld zu verbleiben. Die daraus resultierenden Unterschiede zur Referenzimplementierung sind im Abschnitt Tastatursteuerung beschrieben.

Warum ist der Öffnen-/Schließen-Pfeil nicht per Tab erreichbar?
Der Öffnen-/Schließen-Pfeil dient ausschließlich als zusätzliche Unterstützung für Maus- und Touch-Nutzende. Die Vorschlagsliste kann vollständig über die Tastatur geöffnet und bedient werden, sodass kein zusätzlicher Tabstopp erforderlich ist.

Warum kann ich während der Navigation keinen weiteren Suchtext eingeben?
Während der Navigation innerhalb der Vorschlagsliste befindet sich der Tastaturfokus auf dem aktiven Vorschlag und nicht im Eingabefeld. Zeicheneingaben dienen in diesem Zustand der Navigation innerhalb der Vorschlagsliste und werden nicht in das Eingabefeld übernommen. Mit Esc gelangen Sie zurück in das Eingabefeld.

Warum schließt sich die Vorschlagsliste bei einem eindeutigen Treffer automatisch?
Entspricht die Eingabe exakt dem einzigen passenden Vorschlag, gibt es keine weitere Auswahl mehr. Die Vorschlagsliste wird daher geschlossen, um zu signalisieren, dass bereits ein eindeutiger Wert eingegeben wurde.

Playground

Testen Sie die verschiedenen Eigenschaften der Combobox-Komponente:

Icons

Message

<KolCombobox _label="Programmiersprache" _suggestions={[ "JavaScript", "Python", "SQL", "TypeScript", "Java", "C#", "C++", "C", "PHP", "Go" ]} />

Funktionalitäten

Einfache Combobox

Jedes Feld benötigt mindestens ein Label (_label), um für alle Nutzenden verständlich und zugänglich zu sein. Das Label wird als natives label-Element mit dem Feld verknüpft.

Zusätzlich benötigt die Combobox Vorschläge (_suggestions), aus denen Nutzende während der Eingabe wählen können – ohne Vorschläge bietet sie keinen Mehrwert gegenüber einem einfachen Texteingabefeld. Die Vorschläge werden in einer eigenen Liste angezeigt und nicht über das native datalist-Element. Darstellung und Tastatursteuerung sind daher unabhängig vom Browser.

<KolCombobox _label="Stadt" _suggestions={[ "Berlin", "Düsseldorf", "Hamburg", "Köln", "München", "Nürnberg", "Stuttgart" ]} />

Formularattribute

Mit den folgenden Properties passen Sie das Feld an gängige Formularanforderungen an:

• _disabled: Deaktiviert das Feld. Deaktivierte Felder sind nicht fokussierbar und können nicht bearbeitet werden (mit Bedacht verwenden!).

• _required: Kennzeichnet das Feld als Pflichtfeld.

Die Properties werden 1:1 auf die gleichnamigen nativen HTML-Attribute des input-Elements übertragen. Bei deaktivierter Combobox werden zusätzlich der Clear-Button und der Öffnen-/Schließen-Pfeil ausgeblendet.

<KolCombobox _label="Programmiersprache" _suggestions={[ "JavaScript", "Python", "SQL", "TypeScript", "Java", "C#", "C++", "C", "PHP", "Go" ]} />

Hinweistexte und Fehlermeldungen

Mit _hint und _msg geben Sie Nutzenden zusätzliche Orientierung zur Eingabe und machen Validierungsfehler unmittelbar am Feld sichtbar:

• _hint: Ergänzende Hinweise zur Eingabe (wird immer angezeigt und über aria-describedby mit dem Feld verknüpft)
• _msg: Fehlermeldungen oder Validierungshinweise (wird nur in Verbindung mit _touched angezeigt)
• _touched: Zeigt an, ob das Feld von Nutzenden bereits angefasst wurde, und steuert damit, ob _msg sichtbar wird
• _hideMsg: Unterdrückt die Fehlermeldung am Feld, wenn sie an anderer Stelle dargestellt wird

Hinweis: _msg wird erst dann eingeblendet, wenn _touched auf true gesetzt ist. So werden Validierungsfehler nicht bereits beim ersten Rendern, sondern erst nach einer Interaktion mit dem Feld angezeigt. Handelt es sich um eine Fehlermeldung, wird das Feld zusätzlich über aria-invalid als ungültig gekennzeichnet.

Anwendungsfall für _hideMsg: Besteht eine fachliche Einheit aus mehreren Eingabefeldern innerhalb eines Field-Sets, beispielsweise ein sechsstelliger Bestätigungscode mit einem einzelnen Feld je Stelle, kann eine gemeinsame Fehlermeldung für die gesamte Gruppe sinnvoller sein als eine Meldung je Einzelfeld. In diesem Fall unterdrücken Sie die Fehlermeldung an den einzelnen Feldern über _hideMsg und stellen sie stattdessen einmalig am Field-Set dar.

Wichtig: _hideMsg blendet die Fehlermeldung nicht nur visuell aus. Die Meldung wird weder gerendert noch über aria-describedby mit dem Feld verknüpft – lediglich die Kennzeichnung über aria-invalid bleibt erhalten. Stellen Sie daher sicher, dass die gemeinsame Fehlermeldung auf Anwendungsebene für alle Nutzenden, auch für Nutzende assistiver Technologien, wahrnehmbar ist.

Message

<KolCombobox _hideMsg={false} _hint="Wählen Sie aus der Liste oder geben Sie eine Alternative ein." _label="Programmiersprache" _msg={{ "_description": "Die Programmiersprache ist erforderlich." }} _suggestions={[ "JavaScript", "Python", "SQL", "TypeScript", "Java", "C#", "C++", "C", "PHP", "Go" ]} _touched={true} />

Placeholder

Mit _placeholder zeigen Sie einen Platzhaltertext an, solange noch kein Wert eingegeben bzw. ausgewählt ist – etwa ein Format- oder Eingabebeispiel. Der Platzhalter ist kein Ersatz für die Beschriftung (_label), da er nach der Eingabe verschwindet und von assistiven Technologien nicht zuverlässig ausgegeben wird.

<KolCombobox _label="Programmiersprache" _placeholder="Bitte wählen oder eingeben …" _suggestions={[ "JavaScript", "Python", "SQL", "TypeScript", "Java", "C#", "C++", "C", "PHP", "Go" ]} />

Label ausblenden

Mit _hideLabel blenden Sie das Label visuell aus, um das Feld kompakter zu gestalten. Für assistive Technologien bleibt die Beschriftung als zugänglicher Name (aria-label) weiterhin verfügbar; sehende Nutzende erhalten sie bei Maus-Hover und Tastaturfokus als Tooltip.

<KolCombobox _hideLabel={false} _label="Programmiersprache" _suggestions={[ "JavaScript", "Python", "SQL", "TypeScript", "Java", "C#", "C++", "C", "PHP", "Go" ]} />

Icons

Mit _icons versehen Sie das Feld links und/oder rechts mit zusätzlichen Icons, um visuellen Kontext zu geben.

Verfügbare Positionen sind:

• left: Icon links vom Feld
• right: Icon rechts vom Feld

Wird ein Icon nur über seine Icon-Klasse angegeben, gilt es als dekorativ und wird vor assistiven Technologien verborgen. Trägt ein Icon eine Information, die nicht bereits aus Label oder Hinweis hervorgeht, übergeben Sie es als Objekt mit label – das Icon erhält dann eine zugängliche Beschriftung.

Icons

<KolCombobox _icons={{ "left": "kolicon-kolibri" }} _label="Programmiersprache" _suggestions={[ "JavaScript", "Python", "SQL", "TypeScript", "Java", "C#", "C++", "C", "PHP", "Go" ]} />

Clear-Button

Mit _hasClearButton steuern Sie, ob ein Clear-Button angezeigt wird, über den der aktuelle Wert mit einer einzigen Aktion entfernt werden kann. Der Clear-Button ist standardmäßig aktiv und erscheint, sobald das Eingabefeld Text enthält. Er ist per Tastatur erreichbar und wird ausgeblendet, wenn die Komponente deaktiviert ist (_disabled). Sein zugänglicher Name wird von KoliBri übersetzt bereitgestellt (deutsch: „Auswahl entfernen“) und sehenden Nutzenden zusätzlich als Tooltip angezeigt.

Nach dem Löschen wird die Vorschlagsliste geschlossen und der Fokus in das Eingabefeld gesetzt. Dabei werden die Events input und change mit einem leeren Wert ausgelöst.

<KolCombobox _hasClearButton={true} _label="Programmiersprache" _suggestions={[ "JavaScript", "Python", "SQL", "TypeScript", "Java", "C#", "C++", "C", "PHP", "Go" ]} _value="TypeScript" />

API

Events

Zur Behandlung von Events bzw. Callbacks siehe .

Event	Auslöser	Value
click	Eingabefeld wird angeklickt	-
focus	Komponente erhält den Fokus	-
blur	Komponente verliert den Fokus	-
keydown	Taste wird im Eingabefeld gedrückt	-
input	Wert wird durch Eingabe, Auswahl eines Vorschlags oder den Clear-Button geändert	Aktueller Wert des Eingabefelds
change	Eingabe wurde abgeschlossen, ein Vorschlag übernommen oder der Wert über den Clear-Button gelöscht	Aktueller Wert des Eingabefelds

Properties

Property	Attribute	Description	Type	Default
_accessKey	_access-key	Defines the key combination that can be used to trigger or focus the component's interactive element.	string | undefined	undefined
_ariaDetails	_aria-details	References an external element by ID that provides accessible details for this combobox.	string | undefined	undefined
_disabled	_disabled	Makes the element not focusable and ignore all events.	boolean | undefined	false
_hasClearButton	_has-clear-button	Shows the clear button if enabled.	boolean | undefined	true
_hideLabel	_hide-label	Hides the caption by default and displays the caption text with a tooltip when the interactive element is focused or the mouse is over it.	boolean | undefined	false
_hideMsg	_hide-msg	Hides the error message but leaves it in the DOM for the input's aria-describedby.	boolean | undefined	false
_hint	_hint	Defines the hint text.	string | undefined	''
_icons	_icons	Defines the icon classnames.	string | undefined | { right?: IconOrIconClass | undefined; left?: IconOrIconClass | undefined; }	undefined
_infoPopover	_info-popover	Defines the informational popover after the label.	any	undefined
_label (required)	_label	Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). Set to false to enable the expert slot.	string	undefined
_msg	_msg	Defines the properties for a message rendered as Alert component.	Omit<AlertProps, "_on" | "_label" | "_level" | "_variant" | "_hasCloser"> & { _description: string; } | string | undefined	undefined
_name	_name	Defines the technical name of an input field.	string | undefined	undefined
_on	--	Gibt die EventCallback-Funktionen für das Input-Event an.	InputTypeOnBlur & InputTypeOnClick & InputTypeOnChange & InputTypeOnFocus & InputTypeOnInput & InputTypeOnKeyDown | undefined	undefined
_placeholder	_placeholder	Defines the placeholder for input field. To be shown when there's no value.	string | undefined	undefined
_required	_required	Makes the input element required.	boolean | undefined	false
_shortKey	_short-key	Adds a visual shortcut hint after the label and instructs the screen reader to read the shortcut aloud.	string | undefined	undefined
_suggestions (required)	_suggestions	Suggestions to provide for the input.	W3CInputValue[] | string	undefined
_tooltipAlign	_tooltip-align	Defines where to show the Tooltip preferably: top, right, bottom or left.	"bottom" | "left" | "right" | "top" | undefined	'top'
_touched	_touched	Shows if the input was touched by a user.	boolean | undefined	false
_value	_value	Defines the value of the element.	string | undefined	undefined
_variant	_variant	Defines which variant should be used for presentation.	string | string[] | undefined	undefined

Methods

click

click() => Promise<void>

Clicks the primary interactive element inside this component.

Returns

Type: Promise<void>

focus(options?: KolFocusOptions) => Promise<void>

Sets focus on the internal element.

Parameters

Name	Type	Description
options	KolFocusOptions | undefined

Returns

Type: Promise<void>

getValue() => Promise<string>

Returns the current value.

Returns

Type: Promise<string>

Slots

Slot	Description
	The label of the input field.

---