ts
| Guidance | Practices |
|---|---|
| Do | Provide a visible label so users understand what they are selecting. |
| Do | Use sections and dividers to organize options when the list exceeds ~8 items. |
| Do | Set a meaningful placeholder that hints at the expected selection (e.g. "Choose a country" not "Select..."). |
| Don't | Use for action menus — use Dropdown Menu for triggering commands or navigation. |
| Don't | Use when there are only two options — use a SegmentedControl or radio buttons instead. |
| Don't | Use Selector for navigation — links should be links, not dropdown options. |
| Don't | Use for yes/no or on/off choices — use Switch or CheckboxInput instead. |
| Don't | Put more than ~20 options without sections — consider Typeahead for large lists. |
| Prop | Type | Description |
|---|---|---|
labelrequired | string | Label text for accessibility. |
optionsrequired | XDSSelectorOption[] | Array of items — strings, objects with value/label/icon/disabled, dividers ({type: "divider"}), or sections ({type: "section", title, items}). |
value | string | Currently selected value. |
onChange | (value: string) => void | Callback fired when the selection changes. |
hasClear | boolean (default: false) | Shows a clear (×) button when a value is selected. When true, onChange also accepts null to signal the user cleared the selection. |
placeholder | string (default: 'Select...') | Placeholder text shown when no value is selected. |
size | 'sm' | 'md' | 'lg' (default: 'md') | Size variant for the selector. |
isDisabled | boolean | Disables the selector. |
isLabelHidden | boolean | Visually hides the label while keeping it accessible. |
description | string | Helper text displayed below the label. |
isOptional | boolean | Marks the field as optional. |
isRequired | boolean | Marks the field as required. |
status | {type: 'error' | 'warning' | 'success', message?: string} | Validation status with an optional message. |
children | (item: XDSSelectorOptionData) => ReactNode | Custom render function for each item in the dropdown. |
xstyle | StyleXStyles | StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}. |
| Prop | Type | Description |
|---|---|---|
labelrequired | ReactNode | Primary label text for the item. |
icon | XDSIconType | Icon displayed before the label. See `npx xds docs icons` for valid semantic names. |
description | ReactNode | Secondary description text displayed below the label. |