SingleSelect
Synonyms: Dropdown, Selection field, Simple selection
Description: The SingleSelect component creates a selection box that allows users to select exactly one predefined option from a list. The input field combines the functionality of a text field with a dropdown list and optionally offers a search function to filter the available options.
Example
Rendering of the component with the essential properties. Code can be displayed.
<KolSingleSelect _label="Select" _options={[{"label":"Herr","value":"Herr"},{"label":"Frau","value":"Frau"},{"label":"Firma","value":"Firma"}]} _placeholder="Please select an option" />Accessibility
The SingleSelect component was developed with a focus on accessibility:
- Label requirement: Every instance must have a unique description via the
_labelattribute. This ensures that screen reader users understand what selection they are making. - Hint texts: With
_hint, additional information can be provided that is read aloud by screen readers. - Error messages: With
_msg, error messages can be output that are automatically linked to the input field. - Keyboard navigation: The component is fully operable via keyboard with intuitive navigation through the options list.
- Status display: The selected state is correctly communicated to assistive technologies.
- Required fields: Fields marked with
_requiredare signalled to assistive technologies.
Links and References
Usage
Keyboard Control
| Key | Function |
|---|---|
Tab | Focuses the SingleSelect field or moves to the next element. |
Shift + Tab | Moves to the previous interactive element. |
Space / Enter | Opens the dropdown list or selects the focused option. |
Arrow up | Navigates to the previous option in the list. |
Arrow down | Navigates to the next option in the list. |
Home | Jumps to the first option in the list. |
End | Jumps to the last option in the list. |
Escape | Closes the dropdown list without saving. |
Character | Filters the options by input (when search function is enabled). |
Best Practices / Recommendations
- Meaningful labels: Use clear, understandable descriptions that make the purpose of the selection obvious.
- Sensible options: Do not make the options list too long; use grouping or pagination if needed.
- Use placeholder wisely: The placeholder should only serve as supplementary help, not as an instruction.
- Check default value: Consider whether a reasonable default value should be set to minimise user errors.
- Concrete error messages: Provide meaningful validation error messages via
_msg. - Clear grouping: For many options (more than 15), consider a different component such as a table or Combobox.
- Clear button: If needed, set an explicit submit button to give users confidence.
Use Cases
- Selection of title, salutation or gender in forms
- Selection of a country or region
- Selection of a category or status
- Filtering by a single criterion
- Selection of a date or time from predefined values
- Single selection in settings or configurations
Construction / Technology
Playground
Test the various properties of the SingleSelect component:
<KolSingleSelect _label="Salutation" _options={[{"label":"Herr","value":"Herr"},{"label":"Frau","value":"Frau"},{"label":"Firma","value":"Firma"}]} />Functionality (with Code)
Simple Selection
Standard selection with label and options list:
<KolSingleSelect _label="Select" _options={[{"label":"Herr","value":"Herr"},{"label":"Frau","value":"Frau"},{"label":"Firma","value":"Firma"}]} />Placeholder
A placeholder text is displayed when no option has been selected yet:
<KolSingleSelect _label="Select" _options={[{"label":"Herr","value":"Herr"},{"label":"Frau","value":"Frau"},{"label":"Firma","value":"Firma"}]} _placeholder="Please select an option" />Form Attributes
Standard attributes for forms:
<KolSingleSelect _label="Select" _options={[{"label":"Herr","value":"Herr"},{"label":"Frau","value":"Frau"},{"label":"Firma","value":"Firma"}]} />Available attributes:
_required: Marks the field as required_disabled: Disables the input field_hideLabel: Hides the label visually (remains visible to assistive technologies)_msg: Error messages or validation hints_hideMsg: Hides the error message visually but keeps it in the DOM foraria-describedby
Clear Button
The clear button allows the current selection to be deleted:
<KolSingleSelect _hasClearButton={true} _label="Select" _options={[{"label":"Herr","value":"Herr"},{"label":"Frau","value":"Frau"},{"label":"Firma","value":"Firma"}]} />Icons
Icons can be displayed to the left and right of the input field:
<KolSingleSelect _icons="fa-solid fa-location-dot" _label="Select" _options={[{"label":"Herr","value":"Herr"},{"label":"Frau","value":"Frau"},{"label":"Firma","value":"Firma"}]} />Hint Text and Error Message
Hint texts can be provided before input, error messages after invalid selection:
<KolSingleSelect _hint="Additional hints for the selection" _label="Select" _options={[{"label":"Herr","value":"Herr"},{"label":"Frau","value":"Frau"},{"label":"Firma","value":"Firma"}]} />Dropdown Height
The maximum number of visible options is controlled via _rows:
<KolSingleSelect _label="Select" _options={[{"label":"Herr","value":"Herr"},{"label":"Frau","value":"Frau"},{"label":"Firma","value":"Firma"}]} _rows={3} />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 | Option is selected | value attribute of option |
change | Option is selected | value attribute of option |
API
Overview
The SingleSelect component creates a dropdown list from which exactly one predefined option can be selected.
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 |
_options (required) | _options | Options the user can choose from. | Option<StencilUnknown>[] | string | 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 |
_rows | _rows | Maximum number of visible rows of the element. | number | undefined | undefined |
_shortKey | _short-key | Adds a visual shortcut hint after the label and instructs the screen reader to read the shortcut aloud. | string | undefined | 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. | boolean | null | number | object | string | undefined | null |
Methods
focus
focus() => Promise<void>
Sets focus on the internal element.
Returns
Type: Promise<void>
getValue() => Promise<StencilUnknown>
Returns the current value.
Returns
Type: Promise<StencilUnknown>
Slots
| Slot | Description |
|---|---|
| The label of the input field. |