# ComboBox A combo box combines a text input with a listbox, allowing users to filter a list of options to items matching a query. ## Content `ComboBox` reuses the `ListBox` component, following the [Collection Components API](collections.html?component=ComboBox). It supports ListBox features such as static and dynamic collections, sections, disabled items, links, text slots, asynchronous loading, etc. See the [ListBox docs](ListBox.html) for more details. The following example shows a dynamic collection of items, grouped into sections. ```tsx import {ComboBox, ComboBoxItem} from 'vanilla-starter/ComboBox'; import {ListBoxSection, Collection, Header} from 'react-aria-components'; function Example() { /*- begin collapse -*/ let options = [ {name: 'Fruit', children: [ {name: 'Apple'}, {name: 'Banana'}, {name: 'Orange'}, {name: 'Honeydew'}, {name: 'Grapes'}, {name: 'Watermelon'}, {name: 'Cantaloupe'}, {name: 'Pear'} ]}, {name: 'Vegetable', children: [ {name: 'Cabbage'}, {name: 'Broccoli'}, {name: 'Carrots'}, {name: 'Lettuce'}, {name: 'Spinach'}, {name: 'Bok Choy'}, {name: 'Cauliflower'}, {name: 'Potatoes'} ]} ]; /*- end collapse -*/ return ( /*- begin highlight -*/ {section => (
{section.name}
{item => {item.name}} )} /*- end highlight -*/ ); } ``` ## Selection Use the `defaultSelectedKey` or `selectedKey` prop to set the selected item. The selected key corresponds to the `id` prop of an item. Items can be disabled with the `isDisabled` prop. See the [selection guide](selection.html?component=ComboBox#single-selection) for more details. ```tsx import type {Key} from 'react-aria-components'; import {ComboBox, ComboBoxItem} from 'vanilla-starter/ComboBox'; import {useState} from 'react'; function Example() { let [animal, setAnimal] = useState("bison"); return (
{/*- end highlight -*/} Koala Kangaroo Platypus Bald Eagle Bison Skunk

Current selection: {animal}

); } ``` ### Input value Use the `inputValue` or `defaultInputValue` prop to set the value of the input field. By default, the value will be reverted to the selected item on blur. Set the `allowsCustomValue` prop to enable entering values that are not in the list. ```tsx import type {Key} from 'react-aria-components'; import {ComboBox, ComboBoxItem} from 'vanilla-starter/ComboBox'; import {useState} from 'react'; function Example(props) { let [value, setValue] = useState('Kangaroo'); return (
{/*- end highlight -*/} Koala Kangaroo Platypus Bald Eagle Bison Skunk

Current input value: {value}

); } ``` ### Fully controlled Both `inputValue` and `selectedKey` can be controlled simultaneously. However, each interaction will only trigger either `onInputChange` or `onSelectionChange`, not both. When controlling both props, you must update both values accordingly. ```tsx import type {Key} from 'react-aria-components'; import {ComboBox, ComboBoxItem} from 'vanilla-starter/ComboBox'; import {useState} from 'react'; function ControlledComboBox() { /*- begin collapse -*/ let options = [ {id: 1, name: 'Aerospace'}, {id: 2, name: 'Mechanical'}, {id: 3, name: 'Civil'}, {id: 4, name: 'Biomedical'}, {id: 5, name: 'Nuclear'}, {id: 6, name: 'Industrial'}, {id: 7, name: 'Chemical'}, {id: 8, name: 'Agricultural'}, {id: 9, name: 'Electrical'} ]; /*- end collapse -*/ let [fieldState, setFieldState] = useState({ selectedKey: null, inputValue: '' }); let onSelectionChange = (id: Key) => { // Update inputValue when selectedKey changes. setFieldState({ inputValue: options.find(o => o.id === id)?.name ?? '', selectedKey: id }); }; let onInputChange = (value: string) => { // Reset selectedKey to null if the input is cleared. setFieldState(prevState => ({ inputValue: value, selectedKey: value === '' ? null : prevState.selectedKey })); }; return (
{/*- end highlight -*/} {item => {item.name}} 
        Current selected major id: {fieldState.selectedKey}{'\n'}
        Current input text: {fieldState.inputValue}
); } ``` ## Item actions Use the `onAction` prop on a `` to perform a custom action when the item is pressed. This example adds a "Create" action for the current input value. ```tsx import {ComboBox, ComboBoxItem} from 'vanilla-starter/ComboBox'; import {useState} from 'react'; function Example() { let [inputValue, setInputValue] = useState(''); return ( {/*- begin highlight -*/} {inputValue.length > 0 && ( alert('Creating ' + inputValue)}> {`Create "${inputValue}"`} )} {/*- end highlight -*/} Aardvark Cat Dog Kangaroo Panda Snake ); } ``` ## Forms Use the `name` prop to submit the `id` of the selected item to the server. Set the `isRequired` prop to validate that the user selects a value, or implement custom client or server-side validation. See the Forms guide to learn more. ```tsx import {ComboBox, ComboBoxItem} from 'vanilla-starter/ComboBox'; import {Button} from 'vanilla-starter/Button'; import {Form} from 'vanilla-starter/Form';;
Aardvark Cat Dog Kangaroo Panda Snake
``` ## Popover Use the `menuTrigger` prop to control when the popover opens: * `input` (default): popover opens when the user edits the input text. * `focus`: popover opens when the user focuses the input. * `manual`: popover only opens when the user presses the trigger button or uses the arrow keys. Use `allowsEmptyCollection` to keep the popover open when there are no items available in the list. ```tsx import {ComboBox, ComboBoxItem} from 'vanilla-starter/ComboBox'; Red Panda Cat Dog Aardvark Kangaroo Snake ``` ## API ```tsx