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