Combobox

A combobox is an input widget that has an associated popup that enables users to select a value for the input from a collection of possible values. It combines the functionality of a dropdown and search input, allowing users to either select from a list or type to filter options.

Installation

pnpm add @helgadigitals/vera-ui

npm install @helgadigitals/vera-ui

yarn add @helgadigitals/vera-ui

Usage

import { useState } from "react"
import { Combobox } from "@helgadigitals/vera-ui"

const options = [
{ value: "option1", label: "Option 1" },
{ value: "option2", label: "Option 2" },
{ value: "option3", label: "Option 3" },
]

export default function Example() {
const [value, setValue] = useState("")

return (
  <Combobox
    options={options}
    value={value}
    onValueChange={setValue}
    placeholder="Select an option..."
  />
)
}

import { useState } from "react"import { Combobox } from "@helgadigitals/vera-ui"const options = [{ value: "option1", label: "Option 1" },{ value: "option2", label: "Option 2" },{ value: "option3", label: "Option 3" },]export default function Example() {const [value, setValue] = useState("")return (  <Combobox    options={options}    value={value}    onValueChange={setValue}    placeholder="Select an option..."  />)}

Examples

Basic Combobox

import { useState } from "react"
import { Combobox } from "@helgadigitals/vera-ui"

const frameworks = [
{ value: "react", label: "React" },
{ value: "vue", label: "Vue.js" },
{ value: "angular", label: "Angular" },
{ value: "svelte", label: "Svelte" },
]

export default function BasicExample() {
const [selectedFramework, setSelectedFramework] = useState("")

return (
  <Combobox
    options={frameworks}
    value={selectedFramework}
    onValueChange={setSelectedFramework}
    placeholder="Select a framework..."
  />
)
}

import { useState } from "react"import { Combobox } from "@helgadigitals/vera-ui"const frameworks = [{ value: "react", label: "React" },{ value: "vue", label: "Vue.js" },{ value: "angular", label: "Angular" },{ value: "svelte", label: "Svelte" },]export default function BasicExample() {const [selectedFramework, setSelectedFramework] = useState("")return (  <Combobox    options={frameworks}    value={selectedFramework}    onValueChange={setSelectedFramework}    placeholder="Select a framework..."  />)}

Different States

Loading State

Error State

Disabled State

import { Combobox } from "@helgadigitals/vera-ui"

export default function StatesExample() {
return (
  <div className="space-y-4">
    <div>
      <label className="text-sm font-medium mb-2 block">Loading State</label>
      <Combobox
        options={[]}
        isLoading={true}
        placeholder="Loading options..."
      />
    </div>
    
    <div>
      <label className="text-sm font-medium mb-2 block">Error State</label>
      <Combobox
        options={[]}
        isError={true}
        errorMessage="Failed to load options"
        placeholder="Select an option..."
      />
    </div>
    
    <div>
      <label className="text-sm font-medium mb-2 block">Disabled State</label>
      <Combobox
        options={[
          { value: "option1", label: "Option 1" },
          { value: "option2", label: "Option 2" },
        ]}
        disabled={true}
        placeholder="Disabled combobox..."
      />
    </div>
  </div>
)
}

import { Combobox } from "@helgadigitals/vera-ui"export default function StatesExample() {return (  <div className="space-y-4">    <div>      <label className="text-sm font-medium mb-2 block">Loading State</label>      <Combobox        options={[]}        isLoading={true}        placeholder="Loading options..."      />    </div>        <div>      <label className="text-sm font-medium mb-2 block">Error State</label>      <Combobox        options={[]}        isError={true}        errorMessage="Failed to load options"        placeholder="Select an option..."      />    </div>        <div>      <label className="text-sm font-medium mb-2 block">Disabled State</label>      <Combobox        options={[          { value: "option1", label: "Option 1" },          { value: "option2", label: "Option 2" },        ]}        disabled={true}        placeholder="Disabled combobox..."      />    </div>  </div>)}

API Reference

Props

Prop

Type

Option Object

Property	Type	Required	Description
`label`	`string`	Yes	The text to display for the option
`value`	`string`	Yes	The unique value associated with the option
`icon`	`React.ComponentType<{className?: string}>`	No	Optional icon component to display

Accessibility

The Combobox component follows WAI-ARIA guidelines for combobox patterns:

Keyboard Navigation:
- Arrow keys to navigate options
- Enter to select an option
- Escape to close the popover
- Backspace to clear selection when input is empty
Screen Readers: Proper ARIA attributes and announcements
Focus Management: Focus is properly managed between trigger and popover
Search: Users can type to filter options

Search Functionality: The combobox includes built-in search functionality. Users can type in the input to filter the available options in real-time.

States

The Combobox component supports several visual states:

Default: Normal interactive state
Loading: Shows loading spinner and message
Error: Displays error styling and message
Disabled: Non-interactive state
Empty: When no options are available

Styling

The component uses class-variance-authority (cva) for consistent styling across variants. You can customize the appearance using the className prop:

<Combobox
  className="w-full max-w-md"
  // ... other props
/>

Combobox

On this page