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
<calcite-select>
<calcite-option value="mountains">Mountains</calcite-option>
<calcite-option value="rivers">Rivers</calcite-option>
<calcite-option value="lakes">Lakes</calcite-option>
<calcite-option value="buttes">Buttes</calcite-option>
<calcite-option value="fjords">Fjords</calcite-option>
</calcite-select>
Best practices
Below are important guidelines on using the Select component.
![Correct Select pair with dropdown](/calcite-design-system/static/select-do-multiple-d7fdffb310fc3bd472e9dd02a954affb.png)
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 | The id of the form that will be associated with the component.
When not set, the component will be associated with its ancestor form element, if any. | string | |
label | label | Accessible name for the component. | string | |
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. | "l" | "m" | "s" | "m" |
selectedOption | The component's selected option HTMLElement . | HTMLCalciteOptionElement | ||
status | status | Specifies the status of the input field, which determines message and icons. | "idle" | "invalid" | "valid" | "idle" |
validationIcon | validation-icon | Specifies the validation icon to display under the component. | boolean | string | |
validationMessage | validation-message | Specifies the validation message to display under the component. | string | |
validity | The current validation state of the component. | {
valid: boolean;
badInput: boolean;
customError: boolean;
patternMismatch: boolean;
rangeOverflow: boolean;
rangeUnderflow: boolean;
stepMismatch: boolean;
tooLong: boolean;
tooShort: boolean;
typeMismatch: boolean;
valueMissing: boolean;
} | ||
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. | "auto" | "full" | "half" | "auto" |
Slots
Name | Description |
---|---|
default (unnamed) | A slot for adding calcite-option s. |
Styles
Name | Description |
---|---|
--calcite-select-font-size | Specifies the font size of calcite-option s in the component. |
--calcite-select-text-color | Specifies the text color of calcite-option s 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. |
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<void> |
setFocus | Sets focus on the component. | setFocus(): Promise<void> |