Combobox

This documentation is currently being revised and is in beta status. Content may still change.

This component is being retested for accessibility. The full test is still pending and can only be completed after a release.

Synonyms: Autocomplete, Select, Dropdown

Description: The Combobox is an input component that combines a text field with a list of suggestions displayed below it. Users can type a selection or choose from the suggestions – ideal for scenarios where both free input and predefined options make sense.

Example

Standard Combobox with suggestion list:

<KolCombobox _label="Free input with suggestions" _suggestions={["Mr.","Mrs.","Company"]} />

Accessibility

The Combobox component was developed with a focus on accessibility:

• Label required: Every Combobox must have a visible label via the _label attribute so that screen reader users understand the purpose.
• Keyboard control: Full support for keyboard navigation with clear focus indicators.
• Suggestion list: The suggestion list is implemented as an accessible listbox and is accessible to assistive technologies.
• Error messages: Validation errors can be provided with meaningful messages via the _msg attribute.
• Hint text: With _hint, additional notes can be provided that are read aloud by screen readers.

Links and References

Usage

The suggestion list is provided via the required attribute _suggestions. This can be either a JSON array or a string.

Example of a JSON array:

["Mr.", "Mrs.", "Company"]

Keyboard Controls

Key	Function
Tab	Focuses the input field.
Enter	If the suggestion list is open and an option is focused, selects the focused option and closes the list. Without a focused option, opens the list.
ArrowDown	Opens the suggestion list and moves the focus one option down.
ArrowUp	Opens the suggestion list and moves the focus one option up.
Escape (Esc)	Closes the suggestion list without making a selection.
Home	Moves the focus to the first option in the list.
End	Moves the focus to the last option in the list.
PageUp	Jumps ten options up in the list.
PageDown	Jumps ten options down in the list.
Printable Characters	Focuses the first option that begins with the pressed character (if available).

Best Practices / Recommendations

• Clear suggestions: Only provide relevant and correctly formatted suggestions.
• Meaningful label: Use concise labels that clearly indicate what type of input is expected.
• Sensible defaults: For known frequent inputs, list these as the first suggestions.
• Hint texts: Use _hint to explain format requirements or special features.
• Validation: Use _msg to make validation errors transparent.
• Free input vs. selection: The Combobox allows both — ensure that this freedom is intentional. If only selection is desired, use a Select element instead.

Use Cases

• Country selection: Suggestions for all countries, but free input possible.
• Professions / Positions: A Combobox with common job titles, but input of special roles also possible.
• Salutation: Limited list (Mr., Mrs., etc.), but input of alternatives also possible.
• Product search: Common products as suggestions, but free search possible.
• Tags / Labels: Predefined tags with the ability to add new ones.

Construction / Technics

Playground

Test the various properties of the Combobox component:

Icons

Message

<KolCombobox _label="Selection" _suggestions={["Mr.","Mrs.","Company"]} />

Functionality (with Code)

Label and Caption

The visible label is set via _label.

<KolCombobox _label="Salutation" _suggestions={["Mr.","Mrs.","Company"]} />

Placeholder and Hint Text

The placeholder is displayed when the field is empty. The hint text provides additional guidance:

<KolCombobox _hint="Choose from the list or enter an alternative." _label="Salutation" _placeholder="Please select or type..." _suggestions={["Mr.","Mrs.","Company"]} />

Form Attributes

Standard attributes for forms such as _disabled, _required and _touched:

<KolCombobox _label="Salutation" _suggestions={["Mr.","Mrs.","Company"]} />

Error Messages

Validation errors are displayed via _msg:

Message

<KolCombobox _label="Salutation" _msg="The salutation is required." _suggestions={["Mr.","Mrs.","Company"]} />

Icons

Icons can be added on the left or right via _icons:

Icons

<KolCombobox _icons="fa-solid fa-user" _label="Salutation" _suggestions={["Mr.","Mrs.","Company"]} />

Clear Button

The clear button can be controlled via _hasClearButton (enabled by default):

<KolCombobox _hasClearButton={true} _label="Salutation" _suggestions={["Mr.","Mrs.","Company"]} />

Hidden Caption

The caption can be visually hidden via _hideLabel (remains visible for screen readers):

<KolCombobox _hideLabel={true} _label="Salutation" _suggestions={["Mr.","Mrs.","Company"]} />

Events

For the handling of events or callbacks, see .

Event	Trigger	Value
click	Input field is clicked	-
focus	Input field is focused	-
blur	Input field loses focus	-
input	Value is changed by entering	Current value of the input field
change	Entry has been completed	Current value of the input field
keydown	Key is pressed	-

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.

---