Choose a version:

Select

The select component allows users to choose one option from a dropdown menu. Use select when presenting four or more choices to keep interfaces uncluttered and scannable, or when space is limited.

Select components support option grouping, placeholder text, help text, and validation states to create clear selection interfaces. For more visual selection layouts with radio buttons or checkboxes, use choice list.

Select supports single-value selection only and presents all options in a flat list. For multi-select behavior, use choice list with multiple.

Support

Targets (29)

Supported targets

Anchor to PropertiesProperties

Configure the following properties on the select component.

Anchor to autocomplete autocomplete AutocompleteField | `${} ${AutocompleteField}` | `${} ${AutocompleteField}` | `${} ${} ${AutocompleteField}` | "on" | "off" Default: 'on': A hint about the intended content of the field for browser autofill.

When set to on (the default), this property indicates that the field should support autofill, but you do not have any more semantic information on the intended contents.

When set to off, you are indicating that this field contains sensitive information, or contents that are never saved, like one-time codes.

Alternatively, you can provide value which describes the specific data you would like to be entered into this field during autofill.

Learn more about the set of autocomplete values supported in browsers.
Anchor to disabled disabled boolean Default: false: Whether the field is disabled, preventing any user interaction.
Anchor to error error string: An error message displayed below the field to indicate validation problems. When set, the field is styled with error indicators and the message is announced to screen readers.
Anchor to id id string: A unique identifier for the element. Use this to reference the element in JavaScript, link labels to form controls, or target specific elements for styling or scripting.
Anchor to label label string: The text displayed as the field label, which identifies the purpose of the field to users. This label is associated with the field for accessibility and helps users understand what information to provide.
Anchor to name name string: The name attribute for the field, used to identify the field's value when the form is submitted. Must be unique within the nearest containing form.
Anchor to placeholder placeholder string: The placeholder text displayed in the field when it's empty, providing a hint about the expected input format or value.
Anchor to required required boolean Default: false: Whether the field needs a value. This requirement adds semantic value to the field, but it will not cause an error to appear automatically. If you want to present an error when this field is empty, you can do so with the error property.
Anchor to value value string: The current value for the field. If omitted, the field will be empty.

AutocompleteSection

The “section” scopes the autocomplete data that should be inserted to a specific area of the page. Commonly used when there are multiple fields with the same autocomplete needs in the same page. For example: 2 shipping address forms in the same page.

`section-${string}`

AutocompleteGroup

The contact information group the autocomplete data should be sourced from.

"shipping" | "billing"

Anchor to EventsEvents

The select component provides event callbacks for handling user interactions. Learn more about handling events.

Anchor to blur blur <typeof tagName>: A callback fired when the select loses focus.

Learn more about the blur event.
Anchor to change change <typeof tagName>: A callback fired when the select value changes.

Learn more about the change event.
Anchor to focus focus <typeof tagName>: A callback fired when the select receives focus.

Learn more about the focus event.

CallbackEventListener

A typed event listener for custom element events. The listener receives a `CallbackEvent` with the correct `currentTarget` type for the associated custom element tag.

(EventListener & {
    (event: CallbackEvent<TTagName, Event> & TData): void;
}) | null

CallbackEvent

An event type that narrows the `currentTarget` to the specific HTML element associated with the custom element tag. This provides type-safe event handling in callback listeners.

TEvent & {
    currentTarget: HTMLElementTagNameMap[TTagName];
}

Anchor to OptionOption

Represents a single option within a select component. Use only as a child of s-select components.

Anchor to accessibilityLabel accessibilityLabel string: A label used for users using assistive technologies like screen readers. When set, any children or label supplied will not be announced. This can also be used to display a control without a visual label, while still providing context to users using screen readers.
Anchor to defaultSelected defaultSelected boolean Default: false: Whether the control is selected by default.
Anchor to disabled disabled boolean Default: false: Whether the control is disabled, preventing any user interaction.
Anchor to id id string: A unique identifier for the element. Use this to reference the element in JavaScript, link labels to form controls, or target specific elements for styling or scripting.
Anchor to selected selected boolean Default: false: Whether the control is currently selected.
Anchor to value value string: The value used in form data when the control is checked.

Anchor to ExamplesExamples

Anchor to Select a countrySelect a country

Display a dropdown with pre-defined options and a default selection. This example uses an s-select for country selection with one option pre-selected using defaultSelected.

Select a country

A rendered example of the select component

html

<s-select label="Country/region">

<s-option defaultSelected value="CA">Canada</s-option>

<s-option value="US">United States</s-option>

<s-option value="UK">United Kingdom</s-option>

<s-option value="AU">Australia</s-option>

</s-select>

Anchor to Add placeholder textAdd placeholder text

Display hint text that prompts the buyer to make a selection. This example displays an s-select with a placeholder for language selection.

html

<s-select label="Preferred language" placeholder="Choose a language">

<s-option value="en">English</s-option>

<s-option value="fr">French</s-option>

<s-option value="es">Spanish</s-option>

<s-option value="de">German</s-option>

</s-select>

Anchor to Disable a locked selectionDisable a locked selection

Show a non-interactive dropdown when the selection is determined by another field. This example shows an s-select with the disabled attribute for a locked currency choice.

html

<s-select label="Currency" disabled>

<s-option defaultSelected value="USD">US Dollar (USD)</s-option>

<s-option value="CAD">Canadian Dollar (CAD)</s-option>

<s-option value="EUR">Euro (EUR)</s-option>

<s-option value="GBP">British Pound (GBP)</s-option>

</s-select>

Anchor to Best practicesBest practices

Use for four or more options: For fewer choices, use choice list with radio buttons for better visibility.
Add placeholder text: Set placeholder to guide buyers when no option is selected, such as "Choose a country."
Pre-select common choices: Use defaultSelected on the most common option to reduce the number of interactions for most buyers.

Was this page helpful?