Combobox

Diese Dokumentation wird aktuell überarbeitet und befindet sich im Beta-Status. Inhalte können sich noch ändern.

Synonyme: Autocomplete, Select, Dropdown

Beschreibung: Die Combobox kombiniert ein Texteingabefeld mit einer Vorschlagsliste. Nutzende können einen Wert entweder direkt eingeben oder aus passenden Vorschlägen auswählen.

Während der Eingabe werden die verfügbaren Optionen gefiltert und als Liste angezeigt. Die Filterung erfolgt über eine Substring-Suche, sodass der Suchbegriff an beliebiger Stelle eines Eintrags vorkommen kann. Entspricht die Eingabe eindeutig genau einem vorhandenen Eintrag, schließt sich die Vorschlagsliste automatisch.

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

• Die Combobox orientiert sich am WAI-ARIA Authoring Practices Pattern „Editable Combobox with List Autocomplete“.
• Das Eingabefeld verwendet die ARIA-Rolle combobox mit den Attributen aria-expanded, aria-controls und aria-activedescendant.
• Die Vorschlagsliste wird als eigenständige Listbox (role="listbox") mit Einträgen (role="option") umgesetzt.
• Die Combobox benötigt einen zugänglichen Namen. Dieser wird in der Regel über _label bereitgestellt. Wird _hideLabel verwendet, bleibt die Beschriftung für assistive Technologien weiterhin verfügbar.
• Mit _hint können zusätzliche Hinweise bereitgestellt werden, die mit der Combobox verknüpft und von assistiven Technologien ausgegeben werden.

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.
Die Vorschlagsliste wird als ARIA-basierte Listbox 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-Button (Pfeil-Icon) 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 Tastatur (Pfeil ↓) im Eingabefeld zur Verfügung, sodass unnötige Tabstopps vermieden werden.
Beim Navigieren innerhalb der Vorschlagsliste wird der Tastaturfokus auf die jeweilige Option verschoben.	Anders als im WAI-ARIA APG Pattern verbleibt der Fokus während der Listennavigation nicht im Eingabefeld. Stattdessen wechselt er auf die jeweils aktive Option. Während der Navigation kann daher kein weiterer Suchtext eingegeben werden. Dieses Verhalten ist eine bewusste Designentscheidung der KoliBri-Combobox.

Links und Referenzen

Verwendung

• Verwenden Sie die Combobox, wenn aus einer umfangreichen Menge vordefinierter Optionen ausgewählt werden soll.
• Nutzen Sie die Suchfunktion, um das Auffinden von Einträgen in langen Listen zu erleichtern.
• Verwenden Sie die Combobox ausschließlich für vordefinierte Auswahlmöglichkeiten.
• Verwenden Sie aussagekräftige Beschriftungen (_label).
• Setzen Sie _required, wenn eine Eingabe verpflichtend ist.
• Stellen Sie Validierungsfehler über _msg mit verständlichen und konkreten Fehlermeldungen bereit.
• Verwenden Sie _hint, wenn zusätzliche Hinweise das Ausfüllen des Feldes erleichtern.

Implizites Verhalten

Die Combobox besitzt einige fest implementierte Verhaltensweisen, die bei der Verwendung berücksichtigt werden sollten.

Substring-Filterung

• Die Vorschläge werden über eine Substring-Suche gefiltert.

• Der Suchbegriff muss daher nicht am Anfang eines Eintrags stehen.

  Eingabe üssel -> Treffer Düsseldorf

  Eingabe berg -> Treffer Nürnberg

Automatsiches Schließen der Vorschlagsliste

• Entspricht die Eingabe eindeutig genau einem vorhandenen Eintrag, schließt sich die Vorschlagsliste automatisch.
• Dadurch wird signalisiert, dass bereits eine eindeutige Auswahl getroffen wurde.

Combobox vs. Select

Combobox	Select
Große oder umfangreiche Auswahllisten	Kleine bis mittlere Auswahllisten
Suchfunktion erforderlich	Keine Suchfunktion erforderlich
Schnelles Auffinden von Einträgen durch Filtern	Direkte Auswahl aus allen Optionen
Geeignet bei vielen thematisch ähnlichen Einträgen	Geeignet bei wenigen, gut überschaubaren Optionen

Tastatursteuerung

Taste	Funktion
Tab	Fokus auf die Combobox bzw. das nächste fokussierbare Element setzen.
Shift+Tab	Fokus auf das vorherige fokussierbare Element setzen.
Pfeil-Taste unten	Vorschlagsliste öffnen. Ist die Liste bereits geöffnet, Fokus auf den ersten bzw. nächsten Vorschlag setzen.
Pfeil-Taste oben	Fokus auf den vorherigen Vorschlag setzen.
Pos1/Ende	Fokus auf den ersten/letzten Vorschlag setzen.
Bild-Tasten (hoch/runter)	Zehn Optionen nach oben/unten springen.
Enter	Vorschlagsliste öffnen. Ist die Liste bereits geöffnet, den fokussierten Vorschlag übernehmen. Die Vorschlagsliste bleibt geöffnet und der Fokus verbleibt auf der ausgewählten Option.
Leertaste	Vorschlagsliste öffnen. Ist die Liste bereits geöffnet, den fokussierten Vorschlag übernehmen. Die Vorschlagsliste wird geschlossen und der Fokus auf das Eingabefeld gesetzt.
Esc	Vorschlagsliste schließen ohne eine Auswahl zu treffen und Fokus auf das Eingabefeld setzen.
Zeicheneingabe (Fokus im Eingabefeld)	Vorschlagsliste entsprechend der Eingabe filtern.
Zeicheneingabe (Fokus auf einer Option)	Fokus auf den ersten Eintrag setzen, dessen Beschriftung mit dem eingegebenen Zeichen beginnt. Das Zeichen wird nicht in das Eingabefeld übernommen.

Fokusmodell

Die KoliBri-Combobox orientiert sich am WAI-ARIA Authoring Practices Pattern „Editable Combobox with List Autocomplete“, verwendet jedoch ein bewusst abweichendes Fokusmodell.

Während der Navigation innerhalb der Vorschlagsliste (Pfeil-Tasten, Pos1/Ende, Bild-Tasten) wird der Tastaturfokus auf die jeweils aktive Option 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 Vorschlagsliste kann kein weiterer Suchtext eingegeben werden.
• Zeicheneingaben bei Fokus auf einer Option setzen den Fokus auf den ersten Eintrag, dessen Beschriftung mit dem eingegebenen Zeichen beginnt. Das Zeichen wird nicht in das Eingabefeld übernommen.
• Nach dem Schließen der Vorschlagsliste wird der Fokus auf das Eingabefeld gesetzt.
• Der Öffnen-/Schließen-Button (Pfeil-Icon) ist nicht Teil der Tab-Reihenfolge. Das Öffnen der Vorschlagsliste erfolgt über die Pfeil-Taste unten.

Best Practices / Empfehlungen

• Verwenden Sie die Combobox bei umfangreichen Auswahllisten, in denen Nutzende gezielt nach einem Eintrag suchen sollen.
• Stellen Sie nur relevante, eindeutig bezeichnete und unterscheidbare Optionen bereit.
• Führen Sie häufig verwendete Optionen möglichst am Anfang der Vorschlagsliste auf.
• Nutzen Sie _hint, um Formatvorgaben oder Besonderheiten der Eingabe zu erläutern.
• Stellen Sie Validierungsfehler über _msg mit verständlichen und konkreten Fehlermeldungen bereit.
• Verwenden Sie ein Select, wenn die Anzahl der Optionen überschaubar ist und keine Suchfunktion benötigt wird.

Anwendungsfälle

• Personensuche
• Kunden- oder Lieferantenauswahl
• Produktauswahl in umfangreichen Sortimenten
• Orts- oder Postleitzahlensuche
• Organisations- oder Behördenauswahl
• Auswahl aus umfangreichen Datensätzen

FAQ

Wann sollte eine Combobox statt eines Select verwendet werden? Verwenden Sie eine Combobox bei umfangreichen Auswahllisten, in denen Nutzende einen Eintrag durch Eingabe schneller finden sollen. Ist die Anzahl der Optionen überschaubar und keine Suchfunktion erforderlich, eignet sich ein Select in der Regel besser.

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.

Warum weicht die Tastatursteuerung vom WAI-ARIA APG Pattern ab? Die KoliBri-Combobox orientiert sich am WAI-ARIA Authoring Practices Pattern „Editable Combobox with List Autocomplete“, verwendet jedoch ein angepasstes Fokusmodell. Während der Navigation innerhalb der Vorschlagsliste wird der Tastaturfokus auf die aktive Option verschoben. Die daraus resultierenden Unterschiede zur Referenzimplementierung sind im Abschnitt Tastatursteuerung beschrieben.

Warum ist der Öffnen-/Schließen-Button nicht per Tab erreichbar? Der Öffnen-/Schließen-Button 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 der aktiven Option und nicht im Eingabefeld. Zeicheneingaben dienen in diesem Zustand der Navigation innerhalb der Vorschlagsliste und werden nicht in das Eingabefeld übernommen.

Warum schließt sich die Vorschlagsliste bei einem eindeutigen Treffer automatisch? Die Vorschlagsliste schließt sich automatisch, sobald die Eingabe eindeutig einem vorhandenen Eintrag entspricht.

Konstruktion / Technik

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 (mit Code)

Label und Beschriftung

Die sichtbare Beschriftung wird über _label gesetzt.

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

Platzhalter und Hint-Text

Der Platzhalter wird angezeigt, wenn das Feld leer ist. Der Hint-Text gibt zusätzliche Hinweise:

<KolCombobox _hint="Wählen Sie aus der Liste oder geben Sie eine Alternative ein." _label="Programmiersprache" _placeholder="Bitte wählen oder eingeben..." _suggestions={[ "JavaScript", "Python", "SQL", "TypeScript", "Java", "C#", "C++", "C", "PHP", "Go" ]} />

Formularattribute

Standard-Attribute für Formulare wie _disabled, _required und _touched:

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

Fehlermeldungen

Validierungsfehler werden über _msg dargestellt:

Message

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

Icons

Icons können links oder rechts über _icons hinzugefügt werden:

Icons

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

Clear-Button

Der Clear-Button kann über _hasClearButton gesteuert werden (standardmäßig aktiviert):

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

Versteckte Beschriftung

Die Beschriftung kann über _hideLabel visuell verborgen werden (bleibt für Screenreader sichtbar):

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

Events

Zur Behandlung von Events bzw. Callbacks siehe .

Event	Auslöser	Value
click	Eingabefeld wird angeklickt	-
focus	Eingabefeld wird fokussiert	-
blur	Eingabefeld verliert Fokus	-
input	Wert wird durch Eingabe geändert	Aktueller Wert des Eingabefelds
change	Eingabe wurde abgeschlossen	Aktueller Wert des Eingabefelds
keydown	Taste wird gedrückt	-

API

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
_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 (e.g. _icons="fa-solid fa-user").	string | undefined | { right?: IconOrIconClass | undefined; left?: IconOrIconClass | undefined; }	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 | undefined	undefined

Methods

click

click() => Promise<void>

Clicks the primary interactive element inside this component.

Returns

Type: Promise<void>

focus() => Promise<void>

Sets focus on the internal element.

Returns

Type: Promise<void>

getValue() => Promise<string>

Returns the current value.

Returns

Type: Promise<string>

Slots

Slot	Description
	The label of the input field.

---