Combobox

A select input that allows users to search through a large list of options.

Anatomy

<Combobox.Single
  value={value}
  onValueChange={setValue}
  options={[]}
/>
<Combobox.Multiple
  value={values}
  onValueChange={setValues}
  options={[]}
/>

Usage

import { Combobox } from '@ivaldi/ui'
const [value, setValue] = useState<string | null>(null)

return (
  <Combobox.Single
    value={value}
    onValueChange={setValue}
    options={[
      { value: 'apple', label: 'Apple' },
      { value: 'banana', label: 'Banana' },
      { value: 'orange', label: 'Orange' }
    ]}
  />
)

Multiple Selection

const [values, setValues] = useState<string[]>([])

return (
  <Combobox.Multiple
    value={values}
    onValueChange={setValues}
    options={[
      { value: 'apple', label: 'Apple' },
      { value: 'banana', label: 'Banana' },
      { value: 'orange', label: 'Orange' }
    ]}
  />
)

With Search

const [search, setSearch] = useState('')
const [value, setValue] = useState<string | null>(null)

return (
  <Combobox.Single
    value={value}
    onValueChange={setValue}
    search={search}
    onSearchChange={setSearch}
    options={[
      { value: 'apple', label: 'Apple' },
      { value: 'banana', label: 'Banana' },
      { value: 'orange', label: 'Orange' }
    ]}
    placeholder="Search fruits..."
  />
)

Custom Options

<Combobox.Single
  value={value}
  onValueChange={setValue}
  options={[
    {
      value: 'apple',
      option: (
        <div className="flex items-center gap-2">
          <span className="size-2 rounded-full bg-red-500" />
          Apple
        </div>
      )
    },
    {
      value: 'banana',
      option: (
        <div className="flex items-center gap-2">
          <span className="size-2 rounded-full bg-yellow-500" />
          Banana
        </div>
      )
    }
  ]}
/>

With Groups

<Combobox.Single
  value={value}
  onValueChange={setValue}
  options={[
    { value: 'apple', label: 'Apple' },
    { value: 'banana', label: 'Banana' }
  ]}
>
  <Combobox.Group>
    <Combobox.Item value="apple">Apple</Combobox.Item>
    <Combobox.Item value="banana">Banana</Combobox.Item>
  </Combobox.Group>
  <Combobox.Separator />
  <Combobox.Group>
    <Combobox.Item value="carrot">Carrot</Combobox.Item>
    <Combobox.Item value="broccoli">Broccoli</Combobox.Item>
  </Combobox.Group>
</Combobox.Single>

Combobox.Root Props

Root component for the Combobox using Popover

PropTypeDefault
childrenReactNode—
openboolean—
defaultOpenboolean—
onOpenChangefunction—
modalboolean—

Combobox.Button Props

Button component for triggering the Combobox

PropTypeDefault

Combobox.Content Props

Content component for the Combobox dropdown

PropTypeDefault
panelPropsany—
arrowboolean—
forceMounttrue—
classNamestring—
childrenReactNode—
asChildboolean—
sideenum—
sideOffsetnumber"4"
alignenum—
alignOffsetnumber—
arrowPaddingnumber—
avoidCollisionsboolean—
collisionBoundaryElement | Element[]—
collisionPaddingsee more—
stickyenum—
hideWhenDetachedboolean—
updatePositionStrategyenum—
onEscapeKeyDownfunction—
onPointerDownOutsidefunction—
onFocusOutsidefunction—
onInteractOutsidefunction—
onOpenAutoFocusfunction—
onCloseAutoFocusfunction—
placeholderstring"Select..."
emptyReactNode"No items found."
searchstring—
onSearchChangefunction—

Combobox.Flex Props

Flexible Combobox that can be either single or multiple select

PropTypeDefault
type*enum—
valuestring | string[]—
onValueChangefunction—
optionsT[]—
placeholderstring—
emptyReactNode—
buttonPropsany—
searchstring—
onSearchChangefunction—
classNamestring—
childrenReactNode—
indicatorLimitnumber—
delimiterstring—

Combobox.Group Props

Group component for organizing Combobox items

PropTypeDefault
childrenReactNode—
classNamestring—
asChildboolean—
headingReactNode—
valuestring—
forceMountboolean—

Combobox.Item Props

Individual item component for the Combobox

PropTypeDefault
childrenReactNode—
classNamestring—
asChildboolean—
disabledboolean—
onSelectfunction—
valuestring—
keywordsstring[]—
forceMountboolean—
checkedboolean—

Combobox.Multiple Props

Multi-select Combobox implementation

PropTypeDefault
valuestring[]"[]"
onValueChangefunction—
indicatorLimitnumber—
delimiterstring","
optionsT[]—
placeholderstring"Select..."
emptyReactNode—
buttonPropsany"{}"
searchstring—
onSearchChangefunction—
typeenum—
classNamestring—
childrenReactNode—

Combobox.Separator Props

Separator component for dividing Combobox items

PropTypeDefault
classNamestring—
childrenReactNode—
asChildboolean—
alwaysRenderboolean—

Combobox.Single Props

Single-select Combobox implementation

PropTypeDefault
valuestring—
onValueChangefunction—
optionsT[]—
placeholderstring"Select..."
emptyReactNode—
buttonPropsany"{}"
searchstring—
onSearchChangefunction—
typeenum—
classNamestring—
childrenReactNode—

Combobox.Trigger Props

Trigger component for the Combobox using Popover

PropTypeDefault
typeenum—
classNamestring—
childrenReactNode—
asChildboolean—