## Import
```jsx
import { ComboBox } from "@cfa/react-core";
```
## Live Editor
```jsx
Favorite AnimalCatDogBird
```
## Examples
### Basic Usage
A simple combobox with a label and items.
```jsx
Select an optionItem 1Item 2Item 3
```
### Dynamic Items
You can dynamically render items based on an array of data.
```jsx
function Example() {
const sauces = [
{ id: "1", name: "Chick-fil-A® Sauce" },
{ id: "2", name: "Polynesian Sauce" },
{ id: "3", name: "Honey Mustard Sauce" },
];
return (
Select an item
{(sauce) => {sauce.name}}
);
}
```
### Disabled Items
You can disable specific items using the `disabledKeys` prop.
```jsx
Disabled ItemsItem 1 (Disabled)Item 2 (Disabled)Item 3
```
### Default Selected Item
You can set a default selected item using the `defaultSelectedKey` prop.
```jsx
ItemsItem 1Item 2Item 3
```
### With Description
Add helper text below the combobox by using the `Combobox.Description` component.
```jsx
With DescriptionThis is a descriptionItem 1Item 2Item 3
```
### Custom Error Messages
Error states can be triggered using the `isInvalid` prop and the `Combobox.Error` component for custom messages.
```jsx
With DescriptionThis is a custom error messageItem 1Item 2Item 3
```
### Search Variant
Use the search icon variant for filtering large lists of options.
```jsx
SearchItem 1Item 2Item 3
```
### Compact Size
Use the compact size for tighter layouts.
```jsx
CompactItem 1Item 2Item 3
```
### Clear Button
We provide the `Combobox.ClearButton` component that allows you to have an out of the box experience to allow for reseting the `Combobox` state.
Normally, you would have to use a controlled version of the component and manually handle the state yourself. This component can be used anywhere, as long as it is nested within
the `Combobox.Root`. Pressing the button will result in the state being reset.
```jsx
Sauce
Reset
Chick-fil-A® SaucePolynesian SauceHoney Mustard Sauce
```
### Controlled
Use the `defaultValue` or `value` prop to set the selected item. The value corresponds to the `id` prop of an item.
```jsx
function ControlledExample() {
let [selectedKey, setSelectedKey] = React.useState(null);
return (
<>
Favorite AnimalCatDogBird
Selected: {selectedKey ?? "None"}
);
}
```
### States
The Combobox supports various states including success, invalid, disabled, and read-only.
```jsx
```
### TimePicker
A `TimePicker` can easily be created using the `Combobox` component. Just pass in a static array of times or dynamically create
an Array using your favorite Date/Time library. With this approach you have the flexibility of structuring your data
in a way that makes the most sense for you.
The below example is pretty simple, but you are free to create your times in any way that you want.
```jsx
function DynamicExample() {
const times = [
{ value: "1:00", label: "1:00 AM" },
{ value: "2:00", label: "2:00 AM" },
{ value: "3:00", label: "3:00 AM" },
];
return (
Delivery Time
{(time) => (
{time.label}
)}
);
}
```
### Sections / Grouping
`Combobox` supports using sections to group items. When using sections, it is preferred that you group
all of the available options. Leaving some items as "ungrouped" can sometimes cause confusion.
```jsx
function Example() {
const sauces = [
{ id: "1", name: "Chick-fil-A® Sauce" },
{ id: "2", name: "Polynesian Sauce" },
{ id: "3", name: "Honey Mustard Sauce" },
];
return (
Select an itemGroup 1
{(sauce) => {sauce.name}}
Group 2
{(sauce) => {sauce.name}}
);
}
```
## Props
### Combobox.Root
| Name | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| compact | `boolean` | - | Whether the input is compact or not |
| disableIconAnimation | `boolean` | - | - |
| iconVariant | `"search" \ | "chevron"` | `chevron` | - |
| isSuccess | `boolean` | - | - |
| ref | `Ref` | - | Requires React 19 |
| allowsCustomValue | `boolean` | - | Whether the ComboBox allows a non-item matching input value to be set. |
| allowsEmptyCollection | `boolean` | - | Whether the combo box allows the menu to be open when the collection is empty. |
| aria-describedby | `string` | - | Identifies the element (or elements) that describes the object. |
| aria-details | `string` | - | Identifies the element (or elements) that provide a detailed, extended description for the object. |
| aria-label | `string` | - | Defines a string value that labels the current element. |
| aria-labelledby | `string` | - | Identifies the element (or elements) that labels the current element. |
| autoFocus | `boolean` | - | Whether the element should receive focus on render. |
| children | `ChildrenOrFunction` | - | The children of the component. A function may be provided to alter the children based on component state. |
| className | `ClassNameOrFunction` | `'react-aria-ComboBox'` | The CSS \[className]\(https\://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. A function may be provided to compute the class based on component state. |
| defaultFilter | `(textValue: string, inputValue: string) => boolean` | - | The filter function used to determine if a option should be included in the combo box list. |
| defaultInputValue | `string` | - | The default value of the ComboBox input (uncontrolled). |
| defaultItems | `Iterable` | - | The list of ComboBox items (uncontrolled). |
| defaultSelectedKey | `Key` | - | The initial selected key in the collection (uncontrolled). |
| dir | `string` | - | - |
| disabledKeys | `Iterable` | - | The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with. |
| form | `string` | - | The \`\