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.
Anchor to PropertiesProperties
Configure the following properties on the select component.
- Anchor to iconiconiconrequiredrequired
An icon displayed inside the field to provide visual context about the expected input or field purpose. Commonly used for search fields, currency inputs, or to indicate field type. Accepts any icon name from the icon library or a custom string identifier.
- Anchor to detailsdetailsdetailsstringstringrequiredrequired
Supplementary text displayed below the checkbox to provide additional context, instructions, or help. Use this to explain what checking the box means or provide guidance to users. This text is announced to screen readers.
- Anchor to errorerrorerrorstringstringrequiredrequired
An error message displayed below the checkbox to indicate validation problems. When set, the checkbox is styled with error indicators and the message is announced to screen readers.
- Anchor to labellabellabelstringstringrequiredrequired
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 placeholderplaceholderplaceholderstringstringrequiredrequired
The placeholder text displayed in the field when it's empty, providing a hint about the expected input format or value.
- Anchor to requiredrequiredrequiredbooleanbooleanDefault: falseDefault: falserequiredrequired
Whether the field requires a value before form submission. Displays a visual indicator and adds semantic meaning, but doesn't automatically validate or show errors. Use the
errorproperty to display validation messages.- Anchor to labelAccessibilityVisibilitylabelAccessibilityVisibilitylabelAccessibilityVisibility"visible" | "exclusive""visible" | "exclusive"Default: 'visible'Default: 'visible'requiredrequired
Controls whether the label is visible to all users or only to screen readers.
visible: The label is shown to everyone (default).exclusive: The label is visually hidden but still announced by screen readers.
Use
exclusivewhen the surrounding context makes the label redundant visually, but screen reader users still need it for clarity.- Anchor to valuevaluevaluestringstringrequiredrequired
The value of the currently selected option. When setting this property programmatically, it updates which option appears selected in the dropdown. When reading it, you get the
valueattribute of the currently selected option component.- Anchor to disableddisableddisabledbooleanbooleanDefault: falseDefault: falserequiredrequired
Whether the field is disabled, preventing any user interaction.
- Anchor to idididstringstringrequiredrequired
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 namenamenamestringstringrequiredrequired
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 EventsEvents
The select component provides event callbacks for handling user interactions. Learn more about handling events.
- Anchor to changechangechangeCallbackEventListener<'input'>CallbackEventListener<'input'>requiredrequired
A callback fired when the select value changes.
Learn more about the change event.
- Anchor to inputinputinputCallbackEventListener<'input'>CallbackEventListener<'input'>requiredrequired
A callback fired when the user inputs data into the select.
Learn more about the input event.
CallbackEventListener
A function that handles events from UI components. This type represents an event listener callback that receives a `CallbackEvent` with a strongly-typed `currentTarget`. Use this for component event handlers like `click`, `focus`, `blur`, and other DOM events.
(EventListener & {
(event: CallbackEvent<T>): void;
}) | nullCallbackEvent
An event object with a strongly-typed `currentTarget` property that references the specific HTML element that triggered the event. This type extends the standard DOM `Event` interface and ensures type safety when accessing the element that fired the event.
Event & {
currentTarget: HTMLElementTagNameMap[T];
}Anchor to SlotsSlots
The select component supports slots for additional content placement within the component. Learn more about using slots.
- Anchor to childrenchildrenchildrenHTMLElementHTMLElement
The selectable options displayed in the dropdown list. Accepts option components for individual selectable items, and option group components to organize related options into logical groups with labels.
Anchor to OptionOption
Represents a single option within a select component. Use only as a child of s-select components.
- Anchor to selectedselectedselectedbooleanbooleanDefault: falseDefault: falserequiredrequired
Whether the option is currently selected. Use this for controlled components where you manage the selection state.
- Anchor to defaultSelecteddefaultSelecteddefaultSelectedbooleanbooleanDefault: falseDefault: falserequiredrequired
The initial selected state for uncontrolled components. Use this when you want the option to start selected but don't need to control its state afterward.
- Anchor to valuevaluevaluestringstringrequiredrequired
The value submitted with the form when this checkbox is checked. If not specified, the default value is "on".
- Anchor to disableddisableddisabledbooleanbooleanDefault: falseDefault: falserequiredrequired
Whether the checkbox is disabled, preventing user interaction. Disabled checkboxes appear dimmed and their values aren't submitted with forms.
Anchor to SlotsSlots
The option component supports slots for additional content placement within the component. Learn more about using slots.
- Anchor to childrenchildrenchildrenHTMLElementHTMLElement
The text or elements displayed as the option label, which identifies the selectable choice to users in a dropdown or selection list.
Anchor to OptionGroupOption
Represents a group of options within a select component. Use only as a child of s-select components.
- Anchor to disableddisableddisabledbooleanbooleanDefault: falseDefault: falserequiredrequired
Whether the options within this group can be selected or not.
- Anchor to labellabellabelstringstringrequiredrequired
The user-facing label for this group of options.
Anchor to SlotsSlots
The option group component supports slots for additional content placement within the component. Learn more about using slots.
- Anchor to childrenchildrenchildrenHTMLElementHTMLElement
The selectable options displayed in the dropdown list. Accepts option components for individual selectable items within this group.
Anchor to ExamplesExamples
Let users pick one option from a predefined list. This example pairs a label with selectable options.
Preview
html
Anchor to Add sorting optionsAdd sorting options
Provide sorting controls for lists or tables. This example configures sort options with a pre-selected default value.
Preview
html
Anchor to Add placeholder textAdd placeholder text
Show instructional text before a selection is made. This example uses placeholder text to describe what the user should choose.
Preview
html
Anchor to Show validation errorsShow validation errors
Communicate selection problems clearly to users. This example displays an error message when a required selection is missing.
Preview
html
Anchor to Group options by categoryGroup options by category
Make long option lists easier to scan. This example organizes options into logical groups like geographical regions.
Preview
html
Anchor to Add an iconAdd an icon
Visually indicate the purpose of a select field. This example adds a sort icon that signals filtering functionality.
Preview
html
Anchor to Disable the selectDisable the select
Lock a selection when changes aren't allowed. This example disables a dropdown while preserving its selected value.
Preview
html
Anchor to Best practicesBest practices
- Use for choosing from predefined options: Select works best when merchants pick from a known list of options. When merchants need to enter custom values or search through many options, consider text field with autocomplete or a searchable dropdown pattern instead.
- Organize options thoughtfully: The order of options affects how quickly merchants find what they need. Group related options together, put common choices first, or use alphabetical order when no natural hierarchy exists.
- Make options scannable: Merchants should be able to quickly distinguish between options. Include enough context in each option label so merchants don't need to open and read multiple options to find the right one.
- Handle default selections appropriately: Pre-select an option when there's a clear default choice, but use a placeholder when merchants should make an intentional selection. Avoid confusing merchants with unclear initial states.
- Provide clear validation feedback: When selection is required or invalid, explain what the merchant needs to do. Context-specific error messages help merchants complete forms faster than generic validation messages.
Anchor to LimitationsLimitations
- The component doesn't include search or filtering functionality. For option lists where merchants need to search (like country selection with 200+ countries), implement a custom autocomplete or searchable dropdown pattern.
- The component only supports selecting one option at a time. For multi-select scenarios, use a choice list with checkboxes or build a custom multi-select component.
- Rendering 500+ options can cause performance issues, especially on mobile devices. The browser must render all options in the DOM even though only one's visible.
- Browser native select dropdowns have limited styling capabilities. Dropdown appearance varies by browser and OS, and can't be fully customized with CSS. For custom-styled dropdowns, you must build a custom component using button and menu.
- Options only support plain text. You can't include icons, images, badges, or formatted text within option labels. For rich option content, build a custom dropdown using menu components.