Select | Calcite Design System

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.

Sample

Usage

Interactions that require a native browser selection
Form selection

Component comparison

Select, Combobox, and Dropdown may look similar, but each component is designed for a different use case.

Select

This component

Best for selecting a single option from a small list of options.

Allows single selection.

Supports the native browser select menu with Option text labels only.

Combobox

Alternative

Best for selecting from a large or unknown quantity of options. May have complex needs such as filterable options or custom values.

Allows single, multiple, or no selection.

Supports dropdown menu styling and richer item content such as content-start and content-end slots.

Dropdown

Alternative

Best for choosing items from a floating menu triggered by another element. Often used for immediate actions such as filtering or sorting.

Allows single, multiple, or no selection.

Supports dropdown menu styling and richer item content such as iconStart and iconEnd properties.

Best practices

Recommendations

Do use Select when offering a choice from a list of many items.

Avoid using Select when when offering a choice between two items. Consider Checkbox, Radio Button, Segmented Control, or Switch instead.

Consider Combobox instead of Select for long option lists. Combobox's filtering makes long option lists easier to navigate, especially for assistive technology users.

Accessibility

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`
labelrequired	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"`
selectedOptionread-only		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`
validityread-only		The component's current validation state.	`ValidityState`
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-option`s.
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-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.
--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.	bubblescomposed

Methods

Name	Description	Signature
componentOnReady	Creates a promise that resolves once the component is fully loaded.	`componentOnReady(): Promise<this>`
setFocus	Sets focus on the component.	`setFocus(options?: FocusOptions): Promise<void>`