Field Combobox

A Combobox is a form control that allows the user to select a value from a list of options.

Basic Usage

A Combobox is a form control that allows the user to select a value from a list of options.

Country

import { Field, FieldLabel, FieldCombobox, FieldComboboxTrigger, FieldComboboxValue, FieldComboboxContent, FieldComboboxInput, FieldComboboxList, FieldComboboxEmpty, FieldComboboxGroup, FieldComboboxGroupLabel, FieldComboboxItem, FieldComboboxSeparator, FieldComboboxLoading, Spinner } from "@epilot/volt-ui"

<Field variant="highlight">
  <FieldLabel>Items</FieldLabel>
  <FieldCombobox>
    <FieldComboboxTrigger>
      <FieldComboboxValue placeholder="Select an item">
        {value.label}
      </FieldComboboxValue>
    </FieldComboboxTrigger>
    <FieldComboboxContent className="max-h-56">
      <FieldComboboxInput placeholder="Search items" />
      <FieldComboboxLoading>
        <Spinner />
      </FieldComboboxLoading>
      <FieldComboboxList>
        <FieldComboboxEmpty>No items found</FieldComboboxEmpty>
        <FieldComboboxGroup>
          <FieldComboboxGroupLabel>List</FieldComboboxGroupLabel>
          <FieldComboboxItem value="1">1</FieldComboboxItem>
          <FieldComboboxItem value="2">2</FieldComboboxItem>
          <FieldComboboxItem value="3">3</FieldComboboxItem>
        </FieldComboboxGroup>
        
      </FieldComboboxList>
    </FieldComboboxContent>
  </FieldCombobox>
</Field>

Field Combobox Multi Select

A Combobox can be used to select multiple values from a list of options.

Country

Refer FieldComboboxMultiSelectExample component to see how implement multi select combobox.

API Reference

FieldCombobox

Root component built on Radix Popover.Root. It controls the open state of the dropdown content.

Prop	Type	Default	Description
`open`	boolean	-	Controlled open state of the combobox.
`defaultOpen`	boolean	`false`	Whether the combobox is open on initial render.
`onOpenChange`	(open: boolean) => void	-	Invoked when the popover opens or closes.
`modal`	boolean	`false`	If `true`, focus is trapped inside the popover.

FieldComboboxTrigger

Button that toggles the popover and syncs its ref with the surrounding Field for accessibility. Accepts every Radix Popover.Trigger prop.

Prop	Type	Default	Description
`asChild`	boolean	`false`	Render the trigger as its child component.
`disabled`	boolean	`false`	Disable pointer and keyboard interaction.
`className`	string	-	Extend the default Tailwind classes.

FieldComboboxValue

Displays either custom children (e.g., selected text) or a placeholder.

Prop	Type	Default	Description
`placeholder`	string	required	Text shown when no value is provided.
`children`	ReactNode	-	Optional custom label to display.
`className`	string	-	Extend typography or layout classes.

FieldComboboxContent

Popover surface that wraps the internal Command instance.

Prop	Type	Default	Description
`side`	"top" \| "right" \| "bottom" \| "left"	`"bottom"`	Preferred side to render against the trigger.
`align`	"start" \| "center" \| "end"	`"center"`	Horizontal alignment relative to the trigger.
`sideOffset`	number	`4`	Gap between trigger and content.
`className`	string	-	Customize the popover container.

FieldComboboxInput

Search field that filters the command list. Accepts all CommandInput props.

Prop	Type	Default	Description
`placeholder`	string	`"Search..."`	Hint text shown inside the input.
`value`	string	-	Controlled search query.
`onValueChange`	(value: string) => void	-	Fired whenever the query changes.
`className`	string	-	Extend the input styling.

FieldComboboxPlaceholder

Subtle text helper rendered within the value slot when no selection exists. Renders a plain span.

Prop	Type	Default	Description
`className`	string	-	Customize typography or spacing.

FieldComboboxLoading

Loading state that shows when the combobox is loading. Accepts CommandLoading props.

Prop	Type	Default	Description
`children`	ReactNode	-	Content displayed when the list is loading.
`className`	string	-	Customize spacing or typography.

FieldComboboxList

Scrollable container for list items. Accepts CommandList props.

Prop	Type	Default	Description
`className`	string	-	Adjust padding or height of the list.

FieldComboboxGroup

Wraps related items together. Accepts CommandGroup props.

Prop	Type	Default	Description
`heading`	string	-	Accessible text describing the group.
`className`	string	-	Customize spacing or typography.

FieldComboboxGroupLabel

Label rendered above a group. Built on the shared Label component.

Prop	Type	Default	Description
`children`	ReactNode	-	Text shown inside the label.
`className`	string	-	Extend the preset label classes.

FieldComboboxItem

Selectable row that uses CommandItem under the hood.

Prop	Type	Default	Description
`value`	string	required	Machine-friendly value emitted on selection.
`disabled`	boolean	`false`	Prevents hover/selection behavior.
`className`	string	-	Extend hover/active styles.
`children`	ReactNode	-	Label rendered inside the row.

FieldComboboxItemCheckIcon

Utility component that renders the checkmark indicator and can be placed inside custom items.

Prop	Type	Default	Description
`className`	string	-	Customize icon size or color.

FieldComboboxEmpty

Message shown when the query has no matches. Accepts CommandEmpty props.

Prop	Type	Default	Description
`children`	ReactNode	-	Content displayed when the list is empty.
`className`	string	-	Adjust typography or spacing.

FieldComboboxSeparator

Renders a thin divider between sections. Accepts CommandSeparator props.

Prop	Type	Default	Description
`className`	string	-	Customize spacing or color of the separator.

FieldComboboxTriggerClear

To clear the current selection.

Prop	Type	Default	Description
`className`	string	-	Customize spacing or color of the clear button.
`onClick`	(event: React.MouseEvent<HTMLSpanElement>) => void	-	Fired after propagation is stopped to avoid closing the combobox.

Field Combobox

On this page