ComboBoxNew

Usage

import { ComboBox } from '@heroui/react';

Anatomy

import { ComboBox, Input, Label, Description, Header, ListBox, Separator } from '@heroui/react';

export default () => (
  <ComboBox>
    <Label />
    <ComboBox.InputGroup>
      <Input />
      <ComboBox.Trigger />
    </ComboBox.InputGroup>
    {/* Displays the selected values, primarily used for multiple selection */}
    <ComboBox.Value />
    <Description />
    <ComboBox.Popover>
      <ListBox>
        <ListBox.Item>
          <Label />
          <Description />
          <ListBox.ItemIndicator />
        </ListBox.Item>
        <ListBox.Section>
          <Header />
          <ListBox.Item>
            <Label />
          </ListBox.Item>
        </ListBox.Section>
      </ListBox>
    </ComboBox.Popover>
  </ComboBox>
)

Examples

Full Width

With Description

Required

Disabled

With Disabled Options

With Sections

Controlled

Controlled Input Value

Asynchronous Loading

Default Selected Key

Allows Custom Value

Custom Indicator

Custom Value

Custom Filtering

Render Function

Menu Trigger

Use the menuTrigger prop to control when the popover opens:

• focus (default): popover opens when the user focuses the input
• input: popover opens when the user edits the input text
• manual: popover only opens when the user presses the trigger button or uses the arrow keys

Form Value

Use the formValue prop to control whether the selected item's key or text is submitted in forms. key is the default. When allowsCustomValue is true, the text is always submitted.

Validation Behavior

Use the validationBehavior prop to control how validation is displayed:

• native (default): blocks form submission when the value is missing or invalid
• aria: shows errors in realtime and does not block submission

Custom Validation

Use the validate prop to return an error message when the value is invalid, or true when it is valid.

Read Only

Use the isReadOnly prop to make the ComboBox read-only. The selected value can be focused, but it cannot be changed.

Multiple Selection

Set selectionMode="multiple" to allow selecting more than one option. In multiple selection mode, use ComboBox.Value to display the selected items and pass selectionMode="multiple" to the inner ListBox as well. Selection is controlled with the value / defaultValue (Key[]) props and the onChange handler.

In Surface

When used inside a Surface component, use variant="secondary" to apply the lower emphasis variant suitable for surface backgrounds.

Customization

Tailwind CSS

Global CSS

To customize the ComboBox component classes, you can use the @layer components directive. Learn more.

@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;
  }
}

Styling Reference

HeroUI follows the BEM 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):

Base Classes

• .combo-box - Base ComboBox container
• .combo-box__input-group - Container for the input and trigger button
• .combo-box__value - The selected value display (used in multiple selection)
• .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

ComboBox.InputGroup

ComboBox.Value

Renders the selected values of a ComboBox, or a placeholder if no value is selected. By default the selected items are rendered as a comma separated list. Use the render function to customize this (for example, to display tags).

ComboBox.Trigger

ComboBox.Popover

Render Props

When using render functions with ComboBox, these values are provided:

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.

Related Components