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.

View on Storybook

View source on GitHub

Import

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

Props

NameTypeDefaultRequiredDescription
__experimentalRenderItem( args: { item: ComboboxControlOption; } ) => React.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).

__next40pxDefaultSizeboolean

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

@default false

allowResetboolean

Show a reset button to clear the input.

@default true

expandOnFocusboolean

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

@default true

messages{ /** * The message to announce to screen readers when a suggestion is selected. * * @default `__( 'Item selected.' )` */ selected: string; }

Customizable UI messages.

onChange( value: ComboboxControlProps[ 'value' ] ) => 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.

@default noop

optionsComboboxControlOption[]Yes

The options that can be chosen from.

valuestring | null

The current value of the control.

placeholderstring

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

isLoadingboolean

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

@default false

Examples

Default

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

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

With Custom Render Item

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
                __next40pxDefaultSize
                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 Options

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
                __next40pxDefaultSize
                onFilterValueChange={fn()}
                options={optionsWithDisabledOptions}
                value={ value }
                onChange={ ( ...changeArgs ) => {
					setValue( ...changeArgs );
					onChange?.( ...changeArgs );
				} } />
        </>
    );
};

Not Expand On Focus

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
                __next40pxDefaultSize
                onFilterValueChange={fn()}
                options={countryOptions}
                expandOnFocus={false}
                value={ value }
                onChange={ ( ...changeArgs ) => {
					setValue( ...changeArgs );
					onChange?.( ...changeArgs );
				} } />
        </>
    );
};