Select
Synonyms: Datalist, Dropdown
The Select component creates a selection list from which one or more predefined options can be selected.
Construction
<KolSelect _label="Salutation" _options={[{"label":"Herr","value":"Mr."},{"label":"Frau","value":"Mrs."},{"label":"Firma","value":"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 | Option is selected | value attribute of option |
change | Option is selected | value attribute of option |
Usage
The choices are passed to the component as an object or JSON string via the _options attribute. The values **label** and value must be specified for each option.
Example of the construction of the JSON object:
[
{ "label": "Herr", "value": "Mr." },
{ "label": "Frau", "value": "Mrs." },
{ "label": "Firma", "value": "Company" }
]
Specify individual height
Using the _rows attribute you can switch from a selection menu to a selection field (like _multiple) and set its height.
Best practices
- Do not deactivate options of a select using
disabled. Screen readers (tested with NVDA) count deactivated options and thus display a higher number of choices. - Often the first option is created as “Please select an option” and then deactivated to force a selection. This approach should be avoided.
- Hiding a disabled option using
aria-hiddenis now blocked by modern browsers. If a wildcard option is needed, use a selectable option with an empty value instead. - Use validators to check whether a valid option has been chosen instead of disabling options without giving reasons.
Keyboard controls
| button | Function |
|---|---|
Tab | Focuses the selection field. |
Enter | Opens or closes the selection list. |
Arrow keys (up/down) | Changes the activated element in the selection list. This function is also active when the selection list is collapsed. With multiple selection, you must also hold down the shift key to select several entries. |
Why does Select return a list for a single value? In single mode, Select returns an array with exactly one element. Use a custom value transformer to obtain the single value directly.
Links and references
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 |
_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 |
_multiple | _multiple | Makes the input accept multiple inputs. | boolean | undefined | false |
_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> | Optgroup<StencilUnknown>)[] | string | 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 |
_tabIndex | _tab-index | Defines which tab-index the primary element of the component has. (https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex) | number | 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. | StencilUnknown[] | boolean | null | number | object | string | undefined | undefined |
Methods
focus
focus() => Promise<void>
Sets focus on the internal element.
Returns
Type: Promise<void>
getValue() => Promise<StencilUnknown[] | StencilUnknown>
Returns the selected values.
Returns
Type: Promise<StencilUnknown | StencilUnknown[]>
Slots
| Slot | Description |
|---|---|
| The label of the input field. |