Automattic Design System

Components

ComboboxControl

ComboboxControl is an enhanced version of a SelectControl with the addition of being able to search for options using a search input.

import { ComboboxControl } from '@wordpress/components';

View on Storybook

View in Figma

View source on GitHub

PropsPermalink to this section

NameDefaultDescription
label

ReactNode

If this property is added, a label will be generated using label property as the content.

className

string

help

ReactNode

Additional description for the control.

Only use for meaningful description or instructions for the control. An element containing the description will be programmatically associated to the BaseControl by the means of an aria-describedby attribute.

__nextHasNoMarginBottom

boolean

Start opting into the new margin-free styles that will become the default in a future version.

hideLabelFromVisionfalse

boolean

If true, the label will only be visible to screen readers.

__experimentalRenderItem

(args: { item: ComboboxControlOption; }) => ReactNode

Custom renderer invoked for each option in the suggestion list. The render prop receives as its argument an object containing, under the item key, the single option’s data (directly from the array of data passed to the options prop).

__next36pxDefaultSizefalse

boolean

Deprecated. Use __next40pxDefaultSize instead.

__next40pxDefaultSize

boolean

Start opting into the larger default height that will become the default size in a future version.

allowResettrue

boolean

Show a reset button to clear the input.

expandOnFocustrue

boolean

Automatically expand the dropdown when the control is focused. If the control is clicked, the dropdown will expand regardless of this prop.

messages{ selected: __( 'Item selected.' ), }

{ selected: string; }

Customizable UI messages.

onChange

(value: ComboboxControlValue) => void

Function called with the selected value changes.

onFilterValueChange() => {}

(value: string) => void

Function called when the control’s search input value changes. The argument contains the next input value.

options Required

ComboboxControlOption[]

The options that can be chosen from.

value

ComboboxControlValue | undefined

The current value of the control.

placeholder

string

If passed, the combobox input will show a placeholder string if no values are present.

isLoadingfalse

boolean

Show a spinner (and hide the suggestions dropdown) while data about the matching suggestions (ie the options prop) is loading

ExamplesPermalink to this section

DefaultPermalink to this section

const Default = () => {
    const [ value, setValue ] =
		useState< ComboboxControlProps[ 'value' ] >( null );

    return (
        <>
            <ComboboxControl
                onFilterValueChange={fn()}
                label="Country"
                options={countryOptions}
                help="Help text to describe the control."
                value={ value }
                onChange={ ( ...changeArgs ) => {
					setValue( ...changeArgs );
					onChange?.( ...changeArgs );
				} } />
        </>
    );
};

With Custom Render ItemPermalink to this section

The rendered output of each suggestion can be customized by passing a render function to the __experimentalRenderItem prop. (This is still an experimental feature and is subject to change.)

const WithCustomRenderItem = () => {
    const [ value, setValue ] =
		useState< ComboboxControlProps[ 'value' ] >( null );

    return (
        <>
            <ComboboxControl
                onFilterValueChange={fn()}
                label="Author"
                options={[
                    {
                        value: 'parsley',
                        label: 'Parsley Montana',
                        age: 48,
                        country: 'Germany',
                    },
                    {
                        value: 'cabbage',
                        label: 'Cabbage New York',
                        age: 44,
                        country: 'France',
                    },
                    {
                        value: 'jake',
                        label: 'Jake Weary',
                        age: 41,
                        country: 'United Kingdom',
                    },
                ]}
                __experimentalRenderItem={( { item } ) => {
                    const { label, age, country } = item;
                    return (
                        <div>
                            <div style={ { marginBottom: '0.2rem' } }>{ label }</div>
                            <small>
                                Age: { age }, Country: { country }
                            </small>
                        </div>
                    );
                }}
                value={ value }
                onChange={ ( ...changeArgs ) => {
					setValue( ...changeArgs );
					onChange?.( ...changeArgs );
				} } />
        </>
    );
};

With Disabled OptionsPermalink to this section

You can disable options in the list by setting the disabled property to true for individual items in the option object.

const WithDisabledOptions = () => {
    const [ value, setValue ] =
		useState< ComboboxControlProps[ 'value' ] >( null );

    return (
        <>
            <ComboboxControl
                onFilterValueChange={fn()}
                options={optionsWithDisabledOptions}
                value={ value }
                onChange={ ( ...changeArgs ) => {
					setValue( ...changeArgs );
					onChange?.( ...changeArgs );
				} } />
        </>
    );
};

Not Expand On FocusPermalink to this section

By default, the combobox expands when focused. You can disable this behavior by setting the expandOnFocus prop to false. This is useful when you want to show the suggestions only when the user interacts with the input.

const NotExpandOnFocus = () => {
    const [ value, setValue ] =
		useState< ComboboxControlProps[ 'value' ] >( null );

    return (
        <>
            <ComboboxControl
                onFilterValueChange={fn()}
                options={countryOptions}
                expandOnFocus={false}
                value={ value }
                onChange={ ( ...changeArgs ) => {
					setValue( ...changeArgs );
					onChange?.( ...changeArgs );
				} } />
        </>
    );
};