Combobox

React Combobox components combine a text input with a listbox, allowing users to filter options and select a value from a list. They are often used for search-driven selection, large sets of options, and other layouts where users need to filter through data to find their choice.

Installation

Install the component using the Tailgrids CLI.

npx @tailgrids/cli add combobox

Anatomy

Import the component and pass the required props.

import {
  Combobox,
  ComboboxInput,
  ComboboxInputWrapper,
  ComboboxItem,
  ComboboxList,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxTrigger
} from "@/registry/core/combobox/combobox";

export default function ComboboxExample() {
  return (
    <Combobox>
      <ComboboxInputWrapper>
        <ComboboxInput placeholder="Select fruit" />
        <ComboboxTrigger />
      </ComboboxInputWrapper>
      <ComboboxContent>
        <ComboboxList>
          <ComboboxItem id="apple">Apple</ComboboxItem>
          <ComboboxItem id="banana">Banana</ComboboxItem>
        </ComboboxList>
        <ComboboxEmpty>No results found</ComboboxEmpty>
      </ComboboxContent>
    </Combobox>
  );
}

Examples

With Label and Description

Add a label and description to providing additional context for the selection.

Favorite Language

Choose the language you use most often.

Sections

Group related items together using ComboboxSection and ComboboxHeader.

Multi Selection

The MultiCombobox component allows users to select multiple options, which are displayed as tags.

apple

Controlled

Manage the selection state externally using the value and onChange props.

Selected: 2 items

applebanana

Validation

Mark the combobox as required and display error messages using ComboboxErrorMessage.

Required Selection

Please select a framework to continue.

Disabled

Disable the entire component or individual items to prevent user interaction.

With Avatars

Display items with avatars and secondary text for a more informative selection experience.

Select assigning user

With Icons

Use icons to visually represent categories or types within the combobox.

Custom Tag Rendering

The MultiCombobox component can be customized to render selection tags with different styles.

Frameworks

Command Palette

A minimalist, search-focused design that can be used as a command palette with keyboard shortcut hints.

API Reference

Combobox

The root component that manages the selection state and coordinates between the input and the listbox.

Prop	Type	Default	Description
`value`	`Key`	-	The currently selected key (controlled).
`defaultValue`	`Key`	-	The initial selected key (uncontrolled).
`onChange`	`(key: Key) => void`	-	Handler that is called when the selection changes.
`allowsEmptyCollection`	`boolean`	`true`	Whether the combobox allows an empty collection.
`label`	`string`	-	The label for the combobox (convenience prop).
`description`	`string`	-	The description for the combobox (convenience prop).
`errorMessage`	`string \| ((validation: any) => string)`	-	The error message for the combobox (convenience prop).
`items`	`Iterable<T>`	-	The items to display in the combobox.
`isDisabled`	`boolean`	-	Whether the combobox is disabled.
`isInvalid`	`boolean`	-	Whether the combobox is in an invalid state.
`isRequired`	`boolean`	-	Whether the combobox is required.
`className`	`string`	-	Additional CSS classes to apply to the combobox container.

ComboboxInputWrapper

The wrapper for the input field and trigger button, providing consistent styling.

Prop	Type	Default	Description
`className`	`string`	-	Additional CSS classes to apply to the input wrapper element.

ComboboxInput

The text input field where users type to filter options.

Prop	Type	Default	Description
`className`	`string`	-	Additional CSS classes to apply to the input field.

ComboboxTrigger

The button that toggles the visibility of the listbox.

Prop	Type	Default	Description
`className`	`string`	-	Additional CSS classes to apply to the trigger button.

ComboboxContent

The popover container that holds the listbox of options.

Prop	Type	Default	Description
`isNonModal`	`boolean`	`false`	Whether the popover should be non-modal (doesn't block interaction).
`placement`	`Placement`	-	The placement of the popover relative to the trigger.
`offset`	`number`	-	The distance between the trigger and the popover.
`crossOffset`	`number`	-	The distance along the trigger's edge.
`children`	`ReactNode`	-	The content to be rendered within the popover.
`className`	`string`	-	Additional CSS classes to apply to the popover content.

ComboboxList

The listbox component that renders the collection of items.

Prop	Type	Default	Description
`renderEmptyState`	`() => Node`	-	A function that returns the content to display when the collection is empty.
`className`	`string`	-	Additional CSS classes to apply to the list content.

ComboboxEmpty

A convenience component to display a message when no results are found. Should be placed inside ComboboxContent.

Prop	Type	Default	Description
`className`	`string`	-	Additional CSS classes to apply to the empty message.

ComboboxItem

An individual option within the listbox.

Prop	Type	Default	Description
`id`	`string \| number`	-	The unique identifier for the item.
`textValue`	`string`	-	A text representation of the item's content, used for keyboard navigation and accessibility.
`isDisabled`	`boolean`	-	Whether the item is disabled.
`className`	`string`	-	Additional CSS classes to apply to the item.

ComboboxSection

A container for grouping related items within the listbox.

Prop	Type	Default	Description
`className`	`string`	-	Additional CSS classes to apply to the section container.

ComboboxHeader

The header for a group of items within a section.

Prop	Type	Default	Description
`className`	`string`	-	Additional CSS classes to apply to the header.

MultiCombobox

A specialized combobox for selecting multiple values.

Prop	Type	Default	Description
`value`	`Key[]`	-	The currently selected keys (controlled).
`defaultValue`	`Key[]`	-	The initial selected keys (uncontrolled).
`onChange`	`(keys: Key[]) => void`	-	Handler that is called when the selection changes.
`onSelectionChange`	`(key: Key \| null) => void`	-	Handler called when an individual item is selected.

MultiComboboxDisplay

Renders the selected items as tags above or below the combobox.

Prop	Type	Default	Description
`renderTag`	`(key: Key) => Node`	-	Custom tag renderer.
`className`	`string`	-	Additional CSS classes to apply to the tags container.

The Key type supports string and number. See React Aria's Combobox for more details.

Accessibility

Keyboard Navigation: Supports arrow keys to navigate options, Enter/Space to select, and Escape to close.
Filtering: Type to filter the list of options dynamically.
Screen Readers: Follows W3C ARIA ComboBox design pattern with proper descriptions and state announcements.
Focus Management: Maintains focus within the input while navigating the listbox.

Combobox

CLI

Manual

On this page