Skip to main content
Migrate to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use web components, native UI elements with built-in accessibility, better performance, and consistent styling with Shopify's design system. Check out the migration guide to upgrade your extension.

Select

The Select component lets buyers choose one option from an options menu. Consider the Select component when you have 4 or more options, to avoid cluttering the interface.

Support
Targets (50)

Supported targets

Anchor to SelectPropsSelectProps

Anchor to label
label
string
required

The text displayed as the field label, which identifies the purpose of the field to users.

Anchor to options
options
[]
required

The options a user can select from.

Anchor to autocomplete
autocomplete
| boolean

A hint as to the intended content of the field.

When set to true, 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 false, you are indicating that this field contains sensitive information, or contents that are never saved, like one-time codes. Note that it is impossible to prevent autocomplete in some browsers, so do not depend on its absence.

Alternatively, you can provide an Autocomplete object, which describes the specific data you would like to be entered into this field during autocomplete.

Anchor to disabled
disabled
boolean

Whether the select 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.

Anchor to id
id
string

A unique identifier for the field. When no id is set, a globally unique value will be used instead.

Anchor to name
name
string

An identifier for the field that is unique within the nearest containing Form component.

Anchor to onBlur
onBlur
() => void

A callback fired when the select loses focus.

Anchor to onChange
onChange
(value: string) => void

A callback fired when the select value changes. This callback is called with the string value of the selected option. This component is controlled, so you must store this value in state and reflect it back in the value prop of the select.

Anchor to onFocus
onFocus
() => void

A callback fired when the select receives focus.

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 readonly
readonly
boolean

Whether the select is read-only and can't be edited. Read-only selects remain focusable and their content is announced by screen readers.

Anchor to required
required
boolean

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 prop.

Anchor to value
value
string

The active option for the select. This should match to one of the value properties in the options prop. When not set, the value will default to an empty string, which will show the placeholder text as the "selected value".

Anchor to ExamplesExamples

Anchor to Basic SelectBasic Select

Basic Select

Example

Basic Select

import {
reactExtension,
Select,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
'purchase.checkout.block.render',
() => <Extension />,
);

function Extension() {
return (
<Select
label="Country"
value="2"
options={[
{
value: '1',
label: 'Australia',
},
{
value: '2',
label: 'Canada',
},
{
value: '3',
label: 'France',
},
{
value: '4',
label: 'Japan',
},
{
value: '5',
label: 'Nigeria',
},
{
value: '6',
label: 'United States',
},
]}
/>
);
}
import {extension, Select} from '@shopify/ui-extensions/checkout';

export default extension('purchase.checkout.block.render', (root) => {
const select = root.createComponent(Select, {
label: 'Country',
value: '2',
options: [
{
value: '1',
label: 'Australia',
},
{
value: '2',
label: 'Canada',
},
{
value: '3',
label: 'France',
},
{
value: '4',
label: 'Japan',
},
{
value: '5',
label: 'Nigeria',
},
{
value: '6',
label: 'United States',
},
],
});

root.appendChild(select);
});

Anchor to Using the Select component to display a long list of time choicesUsing the Select component to display a long list of time choices

The Select component is a great choice for displaying a long list of time choices, as it helps conserve valuable space. If the number of options is less than or equal to 5, we recommend using the ChoiceList component. This allows buyers to see all options immediately without opening the Select component.

Using the Select component to display a long list of time choices

The Select component is a great choice for displaying a long list of time choices, as it helps conserve valuable space. If the number of options is less than or equal to 5, we recommend using the [ChoiceList](/docs/api/checkout-ui-extensions/components/forms/choicelist) component. This allows buyers to see all options immediately without opening the Select component.

Using the Select component to display a long list of time choices

import {
reactExtension,
Select,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
'purchase.checkout.block.render',
() => <Extension />,
);

function Extension() {
return (
<Select
label="Pickup time"
value="1"
options={[
{
value: '1',
label: '9:00 AM',
},
{
value: '2',
label: '9:30 AM',
},
{
value: '3',
label: '10:00 AM',
},
{
value: '4',
label: '10:30 AM',
},
{
value: '5',
label: '11:00 AM',
},
{
value: '6',
label: '11:30 AM',
},
]}
/>
);
}
import {extension, Select} from '@shopify/ui-extensions/checkout';

export default extension('purchase.checkout.block.render', (root) => {
const select = root.createComponent(Select, {
label: 'Pickup time',
value: '1',
options: [
{
value: '1',
label: '9:00 AM',
},
{
value: '2',
label: '9:30 AM',
},
{
value: '3',
label: '10:00 AM',
},
{
value: '4',
label: '10:30 AM',
},
{
value: '5',
label: '11:00 AM',
},
{
value: '6',
label: '11:30 AM',
},
],
});

root.appendChild(select);
});

Anchor to Best practicesBest practices

  • Use for four or more options: For fewer choices, use the ChoiceList component 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: Set value to the most common option when it makes sense so most buyers need fewer interactions.

Anchor to LimitationsLimitations

  • No multi-select support is available. Use the ChoiceList component with a string[] value so choices render as checkboxes.
  • No built-in search or filter capability is provided. All options are displayed in a flat list.
Was this page helpful?