Component

Combobox

A searchable select with text-based filtering. Supports both controlled and uncontrolled modes, and either an options prop or fully composed ComboboxItem children.

Options prop

Pass an options array and items render automatically. Disabled options are skipped during keyboard navigation.

Selected: none

Composed items

For full control, compose ComboboxItem children inside ComboboxList.

Installation

$pnpm add @refraction-ui/react-combobox

Usage

tsx
import {
  Combobox,
  ComboboxTrigger,
  ComboboxContent,
  ComboboxInput,
  ComboboxList,
  ComboboxEmpty,
} from '@refraction-ui/react'

const options = [
  { value: 'next', label: 'Next.js' },
  { value: 'astro', label: 'Astro' },
]

export function FrameworkPicker() {
  return (
    <Combobox options={options}>
      <ComboboxTrigger placeholder="Select a framework..." />
      <ComboboxContent>
        <ComboboxInput placeholder="Search..." />
        <ComboboxList />
        <ComboboxEmpty>No framework found.</ComboboxEmpty>
      </ComboboxContent>
    </Combobox>
  )
}

Props

PropTypeDefaultDescription
optionsComboboxOption[]--Array of `{ value, label, disabled? }`. When provided, items are auto-rendered inside `ComboboxList`.
valuestring--Controlled selected value. Pair with `onValueChange`.
defaultValuestring--Initial value for uncontrolled usage.
onValueChange(value: string) => void--Called when the selection changes.
open / defaultOpenboolean--Controlled / uncontrolled open state of the popover.
onOpenChange(open: boolean) => void--Called when the popover opens or closes.
filter(option: ComboboxOption, query: string) => boolean--Custom filter predicate. Defaults to case-insensitive label substring match.
disabledbooleanfalseDisables the whole combobox.