---
name: ComboboxControl
package: '@wordpress/components'
category: Forms
status: stable
canonical: 'https://system.automattic.design/components/comboboxcontrol/'
storybook: 'https://wordpress.github.io/gutenberg/?path=/docs/components-comboboxcontrol--docs'
github: 'https://github.com/WordPress/gutenberg/tree/trunk/packages/components/src/combobox-control'
figma: 'https://www.figma.com/design/jMgzw8IhsMC4gpMbMko4lv/WPDS--Gutenberg-22.3-?node-id=15598-11365'
---

# ComboboxControl

`ComboboxControl` is an enhanced version of a [`SelectControl`](../select-control/README.md) with the addition of
being able to search for options using a search input.

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

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `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.<br>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. |
| `hideLabelFromVision` | `boolean` | `false` | 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). |
| `__next36pxDefaultSize` | `boolean` | `false` | Deprecated. Use `__next40pxDefaultSize` instead. |
| `__next40pxDefaultSize` | `boolean` | — | Start opting into the larger default height that will become the default size in a future version. |
| `allowReset` | `boolean` | `true` | Show a reset button to clear the input. |
| `expandOnFocus` | `boolean` | `true` | Automatically expand the dropdown when the control is focused. If the control is clicked, the dropdown will expand regardless of this prop. |
| `messages` | `{ selected: string; }` | `{ 			selected: __( 'Item selected.' ), 		}` | 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. |
| `isLoading` | `boolean` | `false` | Show a spinner (and hide the suggestions dropdown) while data about the matching suggestions (ie the `options` prop) is loading |


## Examples

### Default

```tsx
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 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.)

```tsx
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 Options

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

```tsx
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 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.

```tsx
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 );
				} } />
        </>
    );
};
```