SelectControl

A complete select field with integrated label and description.

import { SelectControl } from '@wordpress/ui';

LinksPermalink to this section

View on Storybook

View source on GitHub

PropsPermalink to this section

Name	Default	Description
`name`		`string` Identifies the field when a form is submitted.
`form`		`string` Identifies the form that owns the hidden input. Useful when the select is rendered outside the form.
`children`		`ReactNode`
`id`		`string` The id of the Select.
`readOnly`	`false`	`boolean` Whether the user should be unable to choose a different option from the select popup.
`defaultValue`		`SelectItem \| null \| undefined` The uncontrolled value of the select when it’s initially rendered. To render a controlled select, use the `value` prop instead.
`required`	`false`	`boolean` Whether the user must choose a value before submitting a form.
`disabled`	`false`	`boolean` Whether the component should ignore user interaction.
`value`		`SelectItem \| null \| undefined` The value of the select. Use when controlled.
`onValueChange`		`(value: SelectItem \| null, eventDetails: SelectRootChangeEventDetails) => void` Event handler called when the value of the select changes.
`open`		`boolean` Whether the select popup is currently open.
`defaultOpen`	`false`	`boolean` Whether the select popup is initially open. To render a controlled select popup, use the `open` prop instead.
`onOpenChange`		`(open: boolean, eventDetails: SelectRootChangeEventDetails) => void` Event handler called when the select popup is opened or closed.
`autoComplete`		`string` Provides a hint to the browser for autofill.
`itemToStringValue`		`(itemValue: SelectItem) => string` When the item values are objects (`<Select.Item value={object}>`), this function converts the object value to a string representation for form submission. If the shape of the object is `{ value, label }`, the value will be used automatically without needing to specify this prop.
`isItemEqualToValue`		`(itemValue: SelectItem, value: SelectItem) => boolean` Custom comparison logic used to determine if a select item value matches the current selected value. Useful when item values are objects without matching referentially. Defaults to `Object.is` comparison.
`itemToStringLabel`		`(itemValue: SelectItem) => string` When the item values are objects (`<Select.Item value={object}>`), this function converts the object value to a string representation for display in the trigger. If the shape of the object is `{ value, label }`, the label will be used automatically without needing to specify this prop.
`highlightItemOnHover`	`true`	`boolean` Whether moving the pointer over items should highlight them. Disabling this prop allows CSS `:hover` to be differentiated from the `:focus` (`data-highlighted`) state.
`actionsRef`		`RefObject<SelectRootActions \| null>` A ref to imperative actions. `unmount`: Manually unmounts the select. Call this after any externally controlled closing animation finishes.
`onOpenChangeComplete`		`(open: boolean) => void` Event handler called after any animations complete when the select popup is opened or closed.
`modal`	`true`	`boolean` Determines if the select enters a modal state when open. `true`: user interaction is limited to the select: document page scroll is locked and pointer interactions on outside elements are disabled. `false`: user interaction with the rest of the document is allowed. On touch devices, a `true` modal blocks outside taps but leaves the page scrollable unless the popup spans nearly the full viewport width, matching native iOS behavior.
`label` Required		`string` The accessible label. All controls must be labeled.
`description`		`string` The accessible description, associated using `aria-describedby`. For screen reader accessibility, this should only contain plain text, and no semantics such as links.
`details`		`ReactNode` Additional information about the field, which unlike a normal description, can include links and other semantic elements. Do not use this prop when the content is only plain text; use `description` instead.
`hideLabelFromVision`	`false`	`boolean` Whether to visually hide the label while keeping it accessible to screen readers.
`className`		`string` CSS class to apply.
`items`		`SelectItem[]` The array of option items to render in the select.
`popupWidth`	`'content'`	`"anchor" \| "content" \| "sm" \| "md" \| "lg" \| "available"` Controls how the popup width is constrained relative to its anchor. For all presets, the popup is never narrower than its anchor. `'anchor'`: Fixed width matching the anchor width. `'content'`: Width grows with item labels between the anchor and available viewport bounds. `'sm'`: Fixed width at the small surface width token (`--wpds-dimension-surface-width-sm`). `'md'`: Fixed width at the medium surface width token (`--wpds-dimension-surface-width-md`). `'lg'`: Fixed width at the large surface width token (`--wpds-dimension-surface-width-lg`). `'available'`: Fixed width at the available viewport width (`--available-width`).
`placeholder`	`__( 'Select' )`	`ReactNode` Text to show when no value is selected. This is overridden by `triggerContent` if specified, or by a null item’s label in `items`.
`triggerContent`		`ReactNode \| ((item: SelectItem) => ReactNode)` The custom trigger content to use instead of the default. `triggerContent={ ( item ) => item.label }`
`size`	`'default'`	`"default" \| "compact"` The size of the control.
`ref`		`LegacyRef<HTMLButtonElement> \| undefined` Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref).
`key`		`Key \| null \| undefined`

ExamplesPermalink to this section

DefaultPermalink to this section

const Default = () => <SelectControl items={defaultItems} label="Label" description="This is the description." />;

With Custom PlaceholderPermalink to this section

When no value is selected, the trigger shows the default placeholder text.

Use the placeholder prop to customize text shown. Prefer a concise label without a trailing ellipsis.

const WithCustomPlaceholder = () => <SelectControl placeholder="Choose an item" />;

With Null Value OptionPermalink to this section

Use a null item value when users should be able to clear the selected value from the popup.

const WithNullValueOption = () => <SelectControl
    items={nullValueOptionItems}
    label="Theme"
    description="Choose a theme preference."
    defaultValue={nullValueOptionItems[ 0 ]} />;

const VisuallyHiddenLabel = () => <SelectControl hideLabelFromVision />;

With DetailsPermalink to this section

const WithDetails = () => <SelectControl description={undefined} details={DETAILS_EXAMPLE} />;

With Disabled OptionPermalink to this section

const WithDisabledOption = () => <SelectControl
    items={disabledOptionItems}
    label="Label"
    description="This is the description."
    defaultValue={disabledOptionItems[ 0 ]} />;

GroupedPermalink to this section

Options can be organized into labeled groups with SelectControl.Group and SelectControl.GroupLabel. Pass a flat items array for trigger label resolution, and use children to render the grouped popup content.

const Grouped = () => <SelectControl
    label="Fruit"
    description="Choose a fruit."
    items={groupedItems.flatMap( ( group ) => group.items )}>{[
        groupedItems.map( ( group ) => (
            <SelectControl.Group key={ group.label }>
                <SelectControl.GroupLabel>
                    { group.label }
                </SelectControl.GroupLabel>
                { group.items.map( ( item ) => (
                    <SelectControl.Item
                        key={ item.value }
                        value={ item }
                        label={ item.label }
                    >
                        <SelectControl.ItemLabel>
                            { item.label }
                        </SelectControl.ItemLabel>
                    </SelectControl.Item>
                ) ) }
            </SelectControl.Group>
        ) ),
    ]}</SelectControl>;

With Custom Trigger And ItemsPermalink to this section

To customize what is rendered inside the trigger element, pass a render function to the triggerContent prop.

The item list can be customized by passing an array of SelectControl.Item as children. Note that the label prop of a SelectControl.Item is used as the string to match against in the typeahead functionality, while the item content is determined by children.

const WithCustomTriggerAndItems = () => <SelectControl
    items={userOptions}
    label="Label"
    description="This is the description."
    triggerContent={( item ) => <User user={ item } />}
    defaultValue={userOptions[ 0 ]}>{[
        userOptions.map( ( item ) => (
            <SelectControl.Item
                key={ item.value }
                value={ item }
                label={ item.label }
            >
                <SelectControl.ItemLabel>
                    <User user={ item } />
                </SelectControl.ItemLabel>
            </SelectControl.Item>
        ) ),
    ]}</SelectControl>;

With Items Array And Partial CustomizationPermalink to this section

By default, the items array is used to render both the Trigger and the Item list. Passing a custom triggerContent or children in addition to items will override that particular aspect of the behavior. In other words, if you pass both an items array and a custom triggerContent, the Item list in the popover will still be rendered based on the items array.

const WithItemsArrayAndPartialCustomization = () => <SelectControl>{[
        Default.args?.items?.map( ( item ) => (
            <SelectControl.Item
                key={ item.value ?? 'null' }
                value={ item }
                label={ item.label }
                disabled={ item.disabled }
            >
                <SelectControl.ItemLabel>
                    ✨ { item.label }
                </SelectControl.ItemLabel>
            </SelectControl.Item>
        ) ),
    ]}</SelectControl>;

With Item DescriptionPermalink to this section

Pass description on an items entry for supplementary text. It is announced as a description rather than part of the item name. Compose SelectControl.Item children when you need multiple descriptions or custom markup.

const WithItemDescription = () => <SelectControl
    label="Fruit"
    items={[
        {
            value: 'apple',
            label: 'Apple',
            description:
                '99 in stock. Ships in two to three business days.',
        },
        {
            value: 'banana',
            label: 'Banana',
            description: '12 in stock. Restock expected next week.',
        },
    ]} />;

Use popupWidth to control how the popup width is constrained relative to its anchor. Defaults to content so static option lists can grow with their labels.

const PopupWidth = () => <SelectControl label="Label" items={longLabelPopupItems} popupWidth="content" />;

SelectControl

LinksPermalink to this section#

PropsPermalink to this section#

ExamplesPermalink to this section#

DefaultPermalink to this section#

With Custom PlaceholderPermalink to this section#

With Null Value OptionPermalink to this section#

Visually Hidden LabelPermalink to this section#

With DetailsPermalink to this section#

With Disabled OptionPermalink to this section#

GroupedPermalink to this section#

With Custom Trigger And ItemsPermalink to this section#

With Items Array And Partial CustomizationPermalink to this section#

With Item DescriptionPermalink to this section#

Popup WidthPermalink to this section#