Selects are styled versions of the select HTML element containing a menu of Options, which can be grouped with Option Group.
Overview
Select combines Calcite styling with robust functionality of a native dropdown.
Usage
- Interactions that require a native browser selection
- Form selection
Sample
Best practices
Recommendations
Accessibility
Keyboard navigation
| Key | Function |
|---|---|
Arrow down | Selects the next calcite-option. If the current focus is the last calcite-option, focus will not change. |
Arrow up | Selects the previous calcite-option. If the current focus is the first calcite-option, focus will not change. |
Home | Selects the first calcite-option. |
End | Selects the last calcite-option. |
Enter | Opens the component's menu. If the menu is open, selects the currently focused calcite-option. |
Space | Opens the component's menu. |
Tab | Move focus in and out of component. |
Tab and Shift | Move focus in and out of component. |
Esc | If open, closes the component's menu. |
Writing and copy
Typically, you don't need placeholder text. Do not rely on placeholder text's contents, because when text is entered it disappears and can be frustrating for your user.
API reference
Properties
| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
| disabled | disabled | When true, interaction is prevented and the component is displayed with lower opacity. | boolean | false |
| form | form | Specifies the id of the component's associated form.
When not set, the component is associated with its ancestor form element, if one exists. | string | |
| label | label | Specifies an accessible label for the component. | string | |
| labelText | label-text | Specifies the component's label text. | string | |
| messageOverrides | Overrides individual strings used by the component. | Record<string, unknown> | undefined | ||
| name | name | Specifies the name of the component. Required to pass the component's value on form submission. | string | |
| required | required | When true and the component resides in a form,
the component must have a value in order for the form to submit. | boolean | false |
| scale | scale | Specifies the size of the component. | Scale | "m" |
| selectedOption | The component's selected option HTMLElement. | Option | ||
| status | status | Specifies the status of the input field, which determines the message and icons. | Status | "idle" |
| validationIcon | validation-icon | Specifies the validation icon to display under the component. | IconName | boolean | |
| validationMessage | validation-message | Specifies the validation message to display under the component. | string | |
| validity | The component's current validation state. | MutableValidityState | ||
| value | value | The component's selectedOption value. | string | |
| width | width | Specifies the width of the component. [Deprecated] The "half" value is deprecated, use "full" instead. | Extract<Width, "auto" | "half" | "full"> | "auto" |
Slots
| Name | Description |
|---|---|
| default (unnamed) | A slot for adding calcite-options. |
| label-content | A slot for rendering content next to the component's labelText. |
Styles
| Name | Description |
|---|---|
| --calcite-select-font-size | Specifies the font size of calcite-options in the component. |
| --calcite-select-text-color | Specifies the text color of calcite-options in the component. |
| --calcite-select-border-color | Specifies the component's border color. |
| --calcite-select-icon-color | Specifies the component's icon color. |
| --calcite-select-icon-color-hover | Specifies the component's icon color when hovered or active. |
| --calcite-select-background-color | Specifies the component's background color. |
| --calcite-select-corner-radius | Specifies the component's corner radius. |
| --calcite-select-shadow | Specifies the component's shadow. |
Events
| Name | Description | Behavior |
|---|---|---|
| calciteSelectChange | Fires when the selectedOption changes. |
Methods
| Name | Description | Signature |
|---|---|---|
| componentOnReady | Create a promise that resolves once component is fully loaded. | componentOnReady(): Promise<this> |
| setFocus | Sets focus on the component. | setFocus(options?: FocusOptions): Promise<void> |