}> Favorite Animal Aardvark Cat Dog Kangaroo Panda Snake ); } ``` ## Related Components - **Listbox**: Scrollable list of selectable items - **Popover**: Displays content in context with a trigger - **Input**: Single-line text input built on React Aria ## Styling ### Passing Tailwind CSS classes ```tsx import { ComboBox, Input } from '@heroui/react'; function CustomComboBox() { return ( Favorite Animal Item 1 ); } ``` ### Customizing the component classes To customize the ComboBox component classes, you can use the `@layer components` directive.
[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes). ```css @layer components { .combo-box { @apply flex flex-col gap-1; } .combo-box__input-group { @apply relative inline-flex items-center; } .combo-box__trigger { @apply absolute right-0 text-muted; } .combo-box__popover { @apply rounded-lg border border-border bg-surface p-2; } } ``` HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize. ### CSS Classes The ComboBox component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/combo-box.css)): #### Base Classes - `.combo-box` - Base ComboBox container - `.combo-box__input-group` - Container for the input and trigger button - `.combo-box__trigger` - The button that triggers the popover - `.combo-box__popover` - The popover container #### State Classes - `.combo-box[data-invalid="true"]` - Invalid state - `.combo-box[data-disabled="true"]` - Disabled ComboBox state - `.combo-box__trigger[data-focus-visible="true"]` - Focused trigger state - `.combo-box__trigger[data-disabled="true"]` - Disabled trigger state - `.combo-box__trigger[data-open="true"]` - Open trigger state ### Interactive States The component supports both CSS pseudo-classes and data attributes for flexibility: - **Hover**: `:hover` or `[data-hovered="true"]` on trigger - **Focus**: `:focus-visible` or `[data-focus-visible="true"]` on trigger - **Disabled**: `:disabled` or `[data-disabled="true"]` on ComboBox - **Open**: `[data-open="true"]` on trigger ## API Reference ### ComboBox Props | Prop | Type | Default | Description | |------|------|---------|-------------| | `inputValue` | `string` | - | Current input value (controlled) | | `defaultInputValue` | `string` | - | Default input value (uncontrolled) | | `onInputChange` | `(value: string) => void` | - | Handler called when the input value changes | | `selectedKey` | `Key \| null` | - | Current selected key (controlled) | | `defaultSelectedKey` | `Key \| null` | - | Default selected key (uncontrolled) | | `onSelectionChange` | `(key: Key \| null) => void` | - | Handler called when the selection changes | | `isOpen` | `boolean` | - | Sets the open state of the popover (controlled) | | `defaultOpen` | `boolean` | - | Sets the default open state of the popover (uncontrolled) | | `onOpenChange` | `(isOpen: boolean) => void` | - | Handler called when the open state changes | | `items` | `Iterable` | - | The items to display in the listbox | | `disabledKeys` | `Iterable` | - | Keys of disabled items | | `defaultFilter` | `(text: string, inputValue: string) => boolean` | - | Custom filter function for filtering items | | `isDisabled` | `boolean` | - | Whether the ComboBox is disabled | | `isReadOnly` | `boolean` | - | Whether the input can be selected but not changed by the user | | `isRequired` | `boolean` | - | Whether user input is required | | `isInvalid` | `boolean` | - | Whether the ComboBox value is invalid | | `validate` | `(value: ComboBoxValidationValue) => ValidationError \| true \| null \| undefined` | - | A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if `validationBehavior="native"`. For realtime validation, use the `isInvalid` prop instead | | `validationBehavior` | `"native" \| "aria"` | `"native"` | Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA | | `name` | `string` | - | The name of the input, used when submitting an HTML form | | `form` | `string` | - | The id of a `

` element to associate the input with | | `formValue` | `"text" \| "key"` | `"key"` | Whether the text or key of the selected item is submitted as part of an HTML form. When `allowsCustomValue` is `true`, this option does not apply and the text is always submitted | | `autoComplete` | `string` | - | Describes the type of autocomplete functionality | | `autoFocus` | `boolean` | - | Whether the element should receive focus on render | | `allowsCustomValue` | `boolean` | - | Whether the ComboBox allows custom values not in the list | | `allowsEmptyCollection` | `boolean` | - | Whether the ComboBox allows an empty collection | | `menuTrigger` | `"focus" \| "input" \| "manual"` | `"focus"` | The interaction required to display the ComboBox menu | | `shouldFocusWrap` | `boolean` | - | Whether keyboard navigation is circular | | `fullWidth` | `boolean` | `false` | Whether the ComboBox should take full width of its container | | `className` | `string` | - | Additional CSS classes | | `children` | `ReactNode \| RenderFunction` | - | ComboBox content or render function | | `render` | `DOMRenderFunction` | - | Overrides the default DOM element with a custom render function.| ### ComboBox.InputGroup Props | Prop | Type | Default | Description | |------|------|---------|-------------| | `className` | `string` | - | Additional CSS classes | | `children` | `ReactNode` | - | InputGroup content | ### ComboBox.Trigger Props | Prop | Type | Default | Description | |------|------|---------|-------------| | `className` | `string` | - | Additional CSS classes | | `children` | `ReactNode` | - | Custom trigger content | ### ComboBox.Popover Props | Prop | Type | Default | Description | |------|------|---------|-------------| | `placement` | `"bottom" \| "bottom left" \| "bottom right" \| "bottom start" \| "bottom end" \| "top" \| "top left" \| "top right" \| "top start" \| "top end" \| "left" \| "left top" \| "left bottom" \| "start" \| "start top" \| "start bottom" \| "right" \| "right top" \| "right bottom" \| "end" \| "end top" \| "end bottom"` | `"bottom"` | Placement of the popover relative to the trigger | | `className` | `string` | - | Additional CSS classes | | `children` | `ReactNode` | - | Content children | ### RenderProps When using render functions with ComboBox, these values are provided: | Prop | Type | Description | |------|------|-------------| | `state` | `ComboBoxState` | The state of the ComboBox | | `inputValue` | `string` | The current input value | | `selectedKey` | `Key \| null` | The currently selected key | | `selectedItem` | `Node \| null` | The currently selected item | ## Examples ### Basic Usage ```tsx import { ComboBox, Input, Label, ListBox } from '@heroui/react'; Favorite Animal Cat Dog ``` ### With Sections ```tsx import { ComboBox, Input, Label, ListBox, Header, Separator } from '@heroui/react'; Country

North America

United States

Europe

United Kingdom ``` ### Controlled Selection ```tsx import type { Key } from '@heroui/react'; import { ComboBox, Input, Label, ListBox } from '@heroui/react'; import { useState } from 'react'; function ControlledComboBox() { const [selectedKey, setSelectedKey] = useState('cat'); return ( Animal Cat Dog ); } ``` ### Controlled Input Value ```tsx import { ComboBox, Input, Label, ListBox } from '@heroui/react'; import { useState } from 'react'; function ControlledInputComboBox() { const [inputValue, setInputValue] = useState(''); return ( Search Cat Dog ); } ``` ### Asynchronous Loading ```tsx import { Collection, ComboBox, EmptyState, Input, Label, ListBox, ListBoxLoadMoreItem, Spinner } from '@heroui/react'; import { useAsyncList } from '@react-stately/data'; interface Character { name: string; } function AsyncComboBox() { const list = useAsyncList({ async load({cursor, filterText, signal}) { const res = await fetch( cursor || `https://swapi.py4e.com/api/people/?search=${filterText}`, { signal } ); const json = await res.json(); return { items: json.results, cursor: json.next, }; }, }); return ( Pick a Character }> {(item) => ( {item.name} )}

Loading more...

); } ``` ### Custom Filtering ```tsx import { ComboBox, Input, Label, ListBox } from '@heroui/react'; { if (!inputValue) return true; return text.toLowerCase().includes(inputValue.toLowerCase()); }} > Animal Cat Dog ``` ### Menu Trigger Control when the popover opens using the `menuTrigger` prop: ```tsx import { ComboBox, Description, Input, Label, ListBox } from '@heroui/react'; // Opens on focus (default) Favorite Animal Cat Popover opens when the input is focused // Opens when typing Favorite Animal Cat Popover opens when the user edits the input text // Opens only manually Favorite Animal Cat Popover only opens when the trigger button is pressed or arrow keys are used ``` ### Form Value Use the `formValue` prop to control whether the selected item's key or text is submitted in forms: ```tsx import { Button, ComboBox, FieldError, Form, Input, Label, ListBox } from '@heroui/react'; function FormValueExample() { const onSubmit = (e: React.FormEvent) => { e.preventDefault(); const formData = new FormData(e.currentTarget); console.log('Submitted value:', formData.get('animal')); // Will be "cat" (the key) }; return ( {/* Submits the key (default) */} Animal Cat Dog {/* Submits the text */} Animal (text) Cat Dog ); } ``` ### Validation Behavior Control how validation is displayed using the `validationBehavior` prop: ```tsx import { Button, ComboBox, FieldError, Form, Input, Label, ListBox } from '@heroui/react'; function ValidationExample() { return (

{/* Native validation (default) - blocks form submission */} {/* ARIA validation - shows errors in realtime, doesn't block submission */}

); } ``` ### Custom Validation Use the `validate` prop to add custom validation logic: ```tsx import { ComboBox, FieldError, Input, Label, ListBox } from '@heroui/react'; function CustomValidationExample() { return ( { if (!value || value.selectedKey === null) { return 'Please select an animal'; } if (value.selectedKey === 'snake') { return 'Snakes are not allowed'; } return true; }} > Favorite Animal Cat Dog Snake ); } ``` ### Read Only Use the `isReadOnly` prop to make the comboBox read-only: ```tsx import { ComboBox, Input, Label, ListBox } from '@heroui/react'; Favorite Animal Cat Dog ``` ## Accessibility The ComboBox component implements the ARIA comboBox pattern and provides: - Full keyboard navigation support - Screen reader announcements for selection changes and input changes - Proper focus management - Support for disabled states - Typeahead search functionality - HTML form integration - Support for custom values For more information, see the [React Aria ComboBox documentation](https://react-spectrum.adobe.com/react-aria/ComboBox.html).