Combobox
Synonyme: Autocomplete, Select, Dropdown
Beschreibung: Die Combobox ist eine Eingabekomponente, die ein Textfeld mit einer darunter angezeigten Liste von Vorschlägen kombiniert. Nutzer können eine Auswahl tippen oder aus den Vorschlägen wählen – ideal für Szenarien, in denen sowohl freie Eingabe als auch vordefinierte Optionen sinnvoll sind.
Beispiel
Standard-Combobox mit Vorschlagsliste:
<KolCombobox _label="Freie Eingabe mit Vorschlägen" _suggestions={["Herr","Frau","Firma"]} />Barrierefreiheit
Die Combobox-Komponente wurde mit Fokus auf Barrierefreiheit entwickelt:
- Label erforderlich: Jede Combobox muss über das Attribut
_labeleine sichtbare Beschriftung erhalten, damit Screenreader-Nutzer den Zweck verstehen. - Tastatursteuerung: Vollständige Unterstützung für Tastaturnavigation mit klaren Fokusindikatoren.
- Suggestionsliste: Die Vorschlagsliste wird als barrierefreie Listbox implementiert und ist für assistive Technologien zugänglich.
- Fehlermeldungen: Validierungsfehler können über das Attribut
_msgmit aussagekräftigen Meldungen versehen werden. - Hint-Text: Mit
_hintkönnen zusätzliche Hinweise bereitgestellt werden, die von Screenreadern vorgelesen werden.
Links und Referenzen
Verwendung
Die Vorschlagsliste wird über das erforderliche Attribut _suggestions bereitgestellt. Dieses kann entweder ein JSON-Array oder ein String sein.
Beispiel für ein JSON-Array:
["Herr", "Frau", "Firma"]
Tastatursteuerung
| Taste | Funktion |
|---|---|
Tab | Fokussiert das Eingabefeld. |
Enter | Wenn die Vorschlagsliste geöffnet ist und eine Option fokussiert ist, wählt diese die fokussierte Option aus und schließt die Liste. Ohne fokussierte Option öffnet es die Liste. |
Pfeil nach unten (ArrowDown) | Öffnet die Vorschlagsliste und bewegt den Fokus um eine Option nach unten. |
Pfeil nach oben (ArrowUp) | Öffnet die Vorschlagsliste und bewegt den Fokus um eine Option nach oben. |
Escape (Esc) | Schließt die Vorschlagsliste ohne eine Auswahl zu treffen. |
Home | Bewegt den Fokus auf die erste Option in der Liste. |
End | Bewegt den Fokus auf die letzte Option in der Liste. |
PageUp | Springt zehn Optionen nach oben in der Liste. |
PageDown | Springt zehn Optionen nach unten in der Liste. |
Druckbare Zeichen | Fokussiert die erste Option, die mit dem gedrückten Zeichen beginnt (falls vorhanden). |
Best Practices / Empfehlungen
- Klare Vorschläge: Stellen Sie nur relevante und korrekt formatierte Vorschläge bereit.
- Label aussagekräftig: Verwenden Sie prägnante Labels, die deutlich machen, welche Art von Eingabe erwartet wird.
- Sinnvolle Vorgaben: Bei bekannten häufigen Eingaben diese als erste Vorschläge anführen.
- Hinweistexte: Verwenden Sie
_hint, um Formatvorgaben oder Besonderheiten zu erklären. - Validierung: Nutzen Sie
_msg, um Validierungsfehler transparent zu machen. - Freie Eingabe vs. Auswahl: Die Combobox erlaubt beide – stellen Sie sicher, dass diese Freiheit beabsichtigt ist. Wenn nur Auswahl gewünscht ist, verwenden Sie besser ein Select-Element.
Anwendungsfälle
- Länderauswahl: Vorschläge aller Länder, aber freie Eingabe möglich.
- Berufe / Positionen: Ein Combobox mit häufigen Berufsbezeichnungen, aber Eingabe von Spezialrollen auch möglich.
- Anrede: Begrenzte Liste (Herr, Frau, etc.), aber auch Eingabe von Alternativen möglich.
- Produktsuche: Häufige Produkte als Vorschlag, aber freie Suche möglich.
- Tags / Labels: Vordefinierte Tags mit der Möglichkeit, neue hinzuzufügen.
Konstruktion / Technik
Playground
Testen Sie die verschiedenen Eigenschaften der Combobox-Komponente:
<KolCombobox _label="Auswahl" _suggestions={["Herr","Frau","Firma"]} />Funktionalitäten (mit Code)
Label und Beschriftung
Die sichtbare Beschriftung wird über _label gesetzt.
<KolCombobox _label="Anrede" _suggestions={["Herr","Frau","Firma"]} />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="Anrede" _placeholder="Bitte wählen oder eingeben..." _suggestions={["Herr","Frau","Firma"]} />Formularattribute
Standard-Attribute für Formulare wie _disabled, _required und _touched:
<KolCombobox _label="Anrede" _suggestions={["Herr","Frau","Firma"]} />Fehlermeldungen
Validierungsfehler werden über _msg dargestellt:
<KolCombobox _label="Anrede" _msg="Die Anrede ist erforderlich." _suggestions={["Herr","Frau","Firma"]} />Icons
Icons können links oder rechts über _icons hinzugefügt werden:
<KolCombobox _icons="fa-solid fa-user" _label="Anrede" _suggestions={["Herr","Frau","Firma"]} />Clear-Button
Der Clear-Button kann über _hasClearButton gesteuert werden (standardmäßig aktiviert):
<KolCombobox _hasClearButton={true} _label="Anrede" _suggestions={["Herr","Frau","Firma"]} />Versteckte Beschriftung
Die Beschriftung kann über _hideLabel visuell verborgen werden (bleibt für Screenreader sichtbar):
<KolCombobox _hideLabel={true} _label="Anrede" _suggestions={["Herr","Frau","Firma"]} />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" | "_variant" | "_hasCloser" | "_label" | "_level"> & { _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 |
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. |