Combobox

An input with a dropdown list for picking one option or several.

Usage

import {
  Combobox,
  ComboboxInput,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxList,
  ComboboxItem,
} from '@appica/ui-react/combobox'

const frameworks = ['Next.js', 'Remix', 'Astro', 'Nuxt.js', 'SvelteKit', 'SolidStart']

<Combobox items={frameworks}>
  <ComboboxInput placeholder="Search a framework" />
  <ComboboxContent>
    <ComboboxEmpty>No frameworks found.</ComboboxEmpty>
    <ComboboxList>
      {(item) => (
        <ComboboxItem key={item} value={item}>
          {item}
        </ComboboxItem>
      )}
    </ComboboxList>
  </ComboboxContent>
</Combobox>

Combobox is a compound component. The root holds the data (items) and shared options (size, variant, clearable, icon, multiple, grid); the parts compose the input and the filtered popup:

ComboboxInput — the text field, styled like Input. It filters the list as you type. Add adornments with startSlot / endSlot.
ComboboxTrigger / ComboboxValue — a select-style trigger (also styled like Input) that shows the current value and opens the popup. Use it instead of ComboboxInput when the search field should live inside the popup (see Country select).
ComboboxChips / ComboboxChip — a chip-based input for multiple selection, in place of ComboboxInput.
ComboboxContent — the portalled, auto-positioned popup. Accepts the shared floating props.
ComboboxList — the scrollable list. Pass a render function over the filtered items, or static ComboboxItems.
ComboboxItem — one option; its value is what selection reports.
ComboboxEmpty — shown only when the filter matches nothing.

Combobox and Autocomplete are siblings built on the same Base UI primitive. Reach for Combobox when you're picking a value from a set (its chevron, clearable, chips, and grid lean toward selection); use Autocomplete for a leaner typeahead. For a short, known list with no search, use a Select.

Examples

Variants

variant switches the input appearance between a bordered outline (default) and a filled soft field.

'use client'

import {
  Combobox,
  ComboboxInput,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxList,
  ComboboxItem,
} from '@appica/ui-react/combobox'

const frameworks = ['Next.js', 'Remix', 'Astro', 'Nuxt.js', 'SvelteKit', 'SolidStart', 'Gatsby', 'Vite']
const variants = ['outline', 'soft'] as const

export default function ComboboxVariants() {
  return (
    <div className="flex w-full max-w-70 flex-col gap-4">
      {variants.map((variant) => (
        <Combobox key={variant} items={frameworks} variant={variant}>
          <ComboboxInput placeholder="Search a framework" aria-label={`Search (${variant})`} />
          <ComboboxContent>
            <ComboboxEmpty>No frameworks found.</ComboboxEmpty>
            <ComboboxList>
              {(item: string) => (
                <ComboboxItem key={item} value={item}>
                  {item}
                </ComboboxItem>
              )}
            </ComboboxList>
          </ComboboxContent>
        </Combobox>
      ))}
    </div>
  )
}

Sizes

size on the root scales the input, popup radius, and items together — sm, md (default), or lg.

'use client'

import {
  Combobox,
  ComboboxInput,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxList,
  ComboboxItem,
} from '@appica/ui-react/combobox'

const frameworks = ['Next.js', 'Remix', 'Astro', 'Nuxt.js', 'SvelteKit', 'SolidStart', 'Gatsby', 'Vite']
const sizes = ['sm', 'md', 'lg'] as const

export default function ComboboxSizes() {
  return (
    <div className="flex w-full max-w-70 flex-col gap-4">
      {sizes.map((size) => (
        <Combobox key={size} items={frameworks} size={size}>
          <ComboboxInput placeholder="Search a framework" aria-label={`Search (${size})`} />
          <ComboboxContent>
            <ComboboxEmpty>No frameworks found.</ComboboxEmpty>
            <ComboboxList>
              {(item: string) => (
                <ComboboxItem key={item} value={item}>
                  {item}
                </ComboboxItem>
              )}
            </ComboboxList>
          </ComboboxContent>
        </Combobox>
      ))}
    </div>
  )
}

Clearable & chevron

icon (a chevron that toggles the popup) is on by default; turn it off with icon={false}. Set clearable to add a clear (✕) button once there's a value. Both render inside the input.

'use client'

import {
  Combobox,
  ComboboxInput,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxList,
  ComboboxItem,
} from '@appica/ui-react/combobox'

const frameworks = ['Next.js', 'Remix', 'Astro', 'Nuxt.js', 'SvelteKit', 'SolidStart', 'Gatsby', 'Vite']

export default function ComboboxClearable() {
  return (
    <div className="w-full max-w-70">
      <Combobox items={frameworks} defaultValue="Next.js" clearable>
        <ComboboxInput placeholder="Search a framework" aria-label="Search a framework" />
        <ComboboxContent>
          <ComboboxEmpty>No frameworks found.</ComboboxEmpty>
          <ComboboxList>
            {(item: string) => (
              <ComboboxItem key={item} value={item}>
                {item}
              </ComboboxItem>
            )}
          </ComboboxList>
        </ComboboxContent>
      </Combobox>
    </div>
  )
}

Disabled & error states

disabled on the root greys out the input and blocks interaction. Set aria-invalid on the ComboboxInput to paint the error state — it's mirrored to data-invalid. Inside a Field, the input also inherits the field's disabled and invalid state, which is the better choice when you're rendering a validation message.

'use client'

import {
  Combobox,
  ComboboxInput,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxList,
  ComboboxItem,
} from '@appica/ui-react/combobox'

const frameworks = ['Next.js', 'Remix', 'Astro', 'Nuxt.js', 'SvelteKit', 'SolidStart', 'Gatsby', 'Vite']

export default function ComboboxStates() {
  return (
    <div className="flex w-full max-w-70 flex-col gap-4">
      <Combobox items={frameworks} disabled>
        <ComboboxInput placeholder="Disabled" aria-label="Disabled" />
        <ComboboxContent>
          <ComboboxEmpty>No frameworks found.</ComboboxEmpty>
          <ComboboxList>
            {(item: string) => (
              <ComboboxItem key={item} value={item}>
                {item}
              </ComboboxItem>
            )}
          </ComboboxList>
        </ComboboxContent>
      </Combobox>

      <Combobox items={frameworks} defaultValue="Next.js">
        <ComboboxInput aria-invalid placeholder="Search a framework" aria-label="With error" />
        <ComboboxContent>
          <ComboboxEmpty>No frameworks found.</ComboboxEmpty>
          <ComboboxList>
            {(item: string) => (
              <ComboboxItem key={item} value={item}>
                {item}
              </ComboboxItem>
            )}
          </ComboboxList>
        </ComboboxContent>
      </Combobox>
    </div>
  )
}

Start & end slots

ComboboxInput accepts startSlot and endSlot for adornments inside the input frame — a search icon, a shortcut hint, a unit — laid out around the field and its controls.

⌘K

'use client'

import {
  Combobox,
  ComboboxInput,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxList,
  ComboboxItem,
} from '@appica/ui-react/combobox'
import { Search } from '@appica/icons-react'

const commands = ['Open file', 'New window', 'Toggle sidebar', 'Find in files', 'Go to line', 'Command palette']

export default function ComboboxSlots() {
  return (
    <div className="w-full max-w-70">
      <Combobox items={commands} icon={false}>
        <ComboboxInput
          placeholder="Search commands"
          aria-label="Search commands"
          startSlot={<Search className="text-foreground-muted size-4.5" />}
          endSlot={<span className="text-foreground-subtle text-xs">⌘K</span>}
        />
        <ComboboxContent>
          <ComboboxEmpty>No commands found.</ComboboxEmpty>
          <ComboboxList>
            {(item: string) => (
              <ComboboxItem key={item} value={item}>
                {item}
              </ComboboxItem>
            )}
          </ComboboxList>
        </ComboboxContent>
      </Combobox>
    </div>
  )
}

Country select

A searchable country picker with flags. When items are objects, give the root an itemToStringLabel so the input and filter know how to read each one; here the selected country's flag is mirrored into the input through startSlot. The list is long, so its ComboboxList is wrapped in a ScrollArea for a custom, themeable scrollbar (set overflow-y-visible on the list so the ScrollArea owns the scroll).

'use client'

import * as React from 'react'
import {
  Combobox,
  ComboboxInput,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxList,
  ComboboxItem,
} from '@appica/ui-react/combobox'
import { ScrollArea } from '@appica/ui-react/scroll-area'
import { CountryFlagRounded } from '@appica/country-flags-react'
import { World } from '@appica/icons-react'

interface Country {
  code: string
  name: string
}

const countries: Country[] = [
  { code: 'ar', name: 'Argentina' },
  { code: 'au', name: 'Australia' },
  { code: 'be', name: 'Belgium' },
  { code: 'br', name: 'Brazil' },
  { code: 'ca', name: 'Canada' },
  { code: 'cn', name: 'China' },
  { code: 'dk', name: 'Denmark' },
  { code: 'eg', name: 'Egypt' },
  { code: 'fr', name: 'France' },
  { code: 'de', name: 'Germany' },
  { code: 'in', name: 'India' },
  { code: 'it', name: 'Italy' },
  { code: 'jp', name: 'Japan' },
  { code: 'mx', name: 'Mexico' },
  { code: 'nl', name: 'Netherlands' },
  { code: 'no', name: 'Norway' },
  { code: 'pt', name: 'Portugal' },
  { code: 'kr', name: 'South Korea' },
  { code: 'es', name: 'Spain' },
  { code: 'se', name: 'Sweden' },
  { code: 'ch', name: 'Switzerland' },
  { code: 'tr', name: 'Türkiye' },
  { code: 'gb', name: 'United Kingdom' },
  { code: 'us', name: 'United States' },
]

export default function ComboboxCountry() {
  const [selected, setSelected] = React.useState<Country | null>(null)

  return (
    <div className="w-full max-w-70">
      <Combobox
        items={countries}
        value={selected}
        onValueChange={(v) => setSelected(v as Country | null)}
        itemToStringLabel={(item) => (item as Country).name}
        clearable
      >
        <ComboboxInput
          placeholder="Select a country"
          aria-label="Select a country"
          startSlot={
            selected ? (
              <CountryFlagRounded code={selected.code} aria-hidden />
            ) : (
              <World className="text-foreground-muted" />
            )
          }
        />
        <ComboboxContent>
          <ComboboxEmpty>No countries found.</ComboboxEmpty>
          <ScrollArea className="max-h-72">
            <ComboboxList className="overflow-y-visible">
              {(country: Country) => (
                <ComboboxItem key={country.code} value={country}>
                  <CountryFlagRounded code={country.code} data-icon="start" aria-hidden />
                  {country.name}
                </ComboboxItem>
              )}
            </ComboboxList>
          </ScrollArea>
        </ComboboxContent>
      </Combobox>
    </div>
  )
}

For a select-style picker, render a ComboboxTrigger (showing the current ComboboxValue) as the field and move the search ComboboxInput inside ComboboxContent. Set icon={false} on the root so the in-popup input drops its own chevron — the trigger already has one. As with Country select, the long list is wrapped in a ScrollArea for a custom scrollbar.

'use client'

import * as React from 'react'
import {
  Combobox,
  ComboboxTrigger,
  ComboboxValue,
  ComboboxInput,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxList,
  ComboboxItem,
} from '@appica/ui-react/combobox'
import { ScrollArea } from '@appica/ui-react/scroll-area'

const languages = [
  'Arabic',
  'Bengali',
  'Chinese',
  'Czech',
  'Danish',
  'Dutch',
  'English',
  'Finnish',
  'French',
  'German',
  'Greek',
  'Hebrew',
  'Hindi',
  'Hungarian',
  'Indonesian',
  'Italian',
  'Japanese',
  'Korean',
  'Norwegian',
  'Polish',
  'Portuguese',
  'Romanian',
  'Russian',
  'Spanish',
  'Swedish',
  'Thai',
  'Turkish',
  'Ukrainian',
  'Vietnamese',
]

export default function ComboboxPopupSearch() {
  const [value, setValue] = React.useState<string | null>(null)

  return (
    <div className="w-full max-w-70">
      <Combobox items={languages} value={value} onValueChange={(v) => setValue(v as string | null)} icon={false}>
        <ComboboxTrigger aria-label="Select a language">
          <ComboboxValue placeholder="Select a language" />
        </ComboboxTrigger>
        <ComboboxContent>
          <div className="px-2 pb-2 group-data-empty/combobox-content:pt-2">
            <ComboboxInput placeholder="Search a language" aria-label="Search a language" />
          </div>
          <ScrollArea className="max-h-64">
            <ComboboxEmpty>No languages found.</ComboboxEmpty>
            <ComboboxList className="overflow-y-visible">
              {(item: string) => (
                <ComboboxItem key={item} value={item}>
                  {item}
                </ComboboxItem>
              )}
            </ComboboxList>
          </ScrollArea>
        </ComboboxContent>
      </Combobox>
    </div>
  )
}

User select

Rich items with an Avatar, a name, and a trailing role — search a directory and assign a person. The chosen avatar is echoed back into the input via startSlot.

'use client'

import * as React from 'react'
import {
  Combobox,
  ComboboxInput,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxList,
  ComboboxItem,
} from '@appica/ui-react/combobox'
import { Avatar, AvatarImage, AvatarFallback } from '@appica/ui-react/avatar'
import { UserFilled } from '@appica/icons-react'

interface User {
  id: string
  name: string
  role: string
  avatar: string
  initials: string
}

const users: User[] = [
  { id: 'liam', name: 'Liam Hudson', role: 'Admin', avatar: '/avatars/01.jpg', initials: 'LH' },
  { id: 'sarah', name: 'Sarah Jenkins', role: 'User', avatar: '/avatars/02.jpg', initials: 'SJ' },
  { id: 'mateo', name: 'Mateo Rossi', role: 'User', avatar: '/avatars/03.jpg', initials: 'MR' },
  { id: 'ava', name: 'Ava Thompson', role: 'Editor', avatar: '/avatars/04.jpg', initials: 'AT' },
  { id: 'noah', name: 'Noah Patel', role: 'User', avatar: '/avatars/05.jpg', initials: 'NP' },
  { id: 'emma', name: 'Emma Garcia', role: 'User', avatar: '/avatars/06.jpg', initials: 'EG' },
  { id: 'lucas', name: 'Lucas Müller', role: 'Admin', avatar: '/avatars/07.jpg', initials: 'LM' },
  { id: 'olivia', name: 'Olivia Bennett', role: 'User', avatar: '/avatars/08.jpg', initials: 'OB' },
]

export default function ComboboxUsers() {
  const [selected, setSelected] = React.useState<User | null>(null)

  return (
    <div className="w-full max-w-70">
      <Combobox
        items={users}
        value={selected}
        onValueChange={(v) => setSelected(v as User | null)}
        itemToStringLabel={(item) => (item as User).name}
        clearable
      >
        <ComboboxInput
          placeholder="Assign to…"
          aria-label="Assign to"
          startSlot={
            <Avatar size={22}>
              {selected && <AvatarImage src={selected.avatar} alt={selected.name} />}
              <AvatarFallback>{selected ? selected.initials : <UserFilled />}</AvatarFallback>
            </Avatar>
          }
        />
        <ComboboxContent>
          <ComboboxEmpty>No people found.</ComboboxEmpty>
          <ComboboxList>
            {(user: User) => (
              <ComboboxItem key={user.id} value={user} className="[&>span:first-child]:flex-1">
                <Avatar size={22} data-icon="start">
                  <AvatarImage src={user.avatar} alt={user.name} />
                  <AvatarFallback>{user.initials}</AvatarFallback>
                </Avatar>
                {user.name}
                <span className="text-foreground-muted ms-auto ps-3 text-xs">{user.role}</span>
              </ComboboxItem>
            )}
          </ComboboxList>
        </ComboboxContent>
      </Combobox>
    </div>
  )
}

Grouped options

Pass a grouped items array — { value, items }[] — and render each group with ComboboxGroup + ComboboxLabel + ComboboxCollection. The outer render function iterates groups; ComboboxCollection renders the items inside each. As with Country select, this longer list wraps its ComboboxList in a ScrollArea for a custom scrollbar.

'use client'

import {
  Combobox,
  ComboboxInput,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxList,
  ComboboxItem,
  ComboboxGroup,
  ComboboxLabel,
  ComboboxCollection,
} from '@appica/ui-react/combobox'
import { ScrollArea } from '@appica/ui-react/scroll-area'

interface ProduceGroup {
  value: string
  items: string[]
}

const groups: ProduceGroup[] = [
  { value: 'Fruits', items: ['Apple', 'Banana', 'Cherry', 'Grapefruit', 'Mango', 'Orange', 'Strawberry'] },
  { value: 'Vegetables', items: ['Broccoli', 'Carrot', 'Cucumber', 'Lettuce', 'Potato', 'Spinach', 'Tomato'] },
  { value: 'Herbs', items: ['Basil', 'Mint', 'Oregano', 'Parsley', 'Rosemary', 'Thyme'] },
]

export default function ComboboxGrouped() {
  return (
    <div className="w-full max-w-70">
      <Combobox items={groups}>
        <ComboboxInput placeholder="Search produce" aria-label="Search produce" />
        <ComboboxContent>
          <ComboboxEmpty>No produce found.</ComboboxEmpty>
          <ScrollArea className="max-h-72">
            <ComboboxList className="overflow-y-visible">
              {(group: ProduceGroup) => (
                <ComboboxGroup key={group.value} items={group.items}>
                  <ComboboxLabel>{group.value}</ComboboxLabel>
                  <ComboboxCollection>
                    {(item: string) => (
                      <ComboboxItem key={item} value={item}>
                        {item}
                      </ComboboxItem>
                    )}
                  </ComboboxCollection>
                </ComboboxGroup>
              )}
            </ComboboxList>
          </ScrollArea>
        </ComboboxContent>
      </Combobox>
    </div>
  )
}

Grid layout

Set grid on the root to lay options out in a grid — arrow keys then move in two dimensions. ComboboxList's cols controls how many items per row (defaults to 2 in grid mode); give each item flex-1 to fill its cell.

'use client'

import {
  Combobox,
  ComboboxInput,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxList,
  ComboboxItem,
} from '@appica/ui-react/combobox'

const tags = ['React', 'Vue', 'Svelte', 'Angular', 'Solid', 'Qwik', 'Preact', 'Lit', 'Alpine', 'Ember']

export default function ComboboxGrid() {
  return (
    <div className="w-full max-w-70">
      <Combobox items={tags} grid>
        <ComboboxInput placeholder="Search a library" aria-label="Search a library" />
        <ComboboxContent>
          <ComboboxEmpty>No libraries found.</ComboboxEmpty>
          <ComboboxList cols={2}>
            {(item: string) => (
              <ComboboxItem key={item} value={item} className="flex-1">
                {item}
              </ComboboxItem>
            )}
          </ComboboxList>
        </ComboboxContent>
      </Combobox>
    </div>
  )
}

Multiple selection

Set multiple and swap ComboboxInput for ComboboxChips: each selected value becomes a removable ComboboxChip, with the text field inline for adding more. The value is an array.

'use client'

import * as React from 'react'
import {
  Combobox,
  ComboboxChips,
  ComboboxChip,
  ComboboxValue,
  ComboboxInput,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxList,
  ComboboxItem,
} from '@appica/ui-react/combobox'

const frameworks = ['Next.js', 'Remix', 'Astro', 'Nuxt.js', 'SvelteKit', 'SolidStart', 'Gatsby', 'Vite']

export default function ComboboxMultiple() {
  const [value, setValue] = React.useState<string[]>(['Next.js', 'Astro'])

  return (
    <div className="w-full max-w-70">
      <Combobox items={frameworks} multiple value={value} onValueChange={(v) => setValue(v as string[])}>
        <ComboboxChips placeholder="Add frameworks">
          <ComboboxValue>
            {(selected: string[]) =>
              selected.map((item) => (
                <ComboboxChip key={item} aria-label={item}>
                  {item}
                </ComboboxChip>
              ))
            }
          </ComboboxValue>
        </ComboboxChips>
        <ComboboxContent>
          <ComboboxEmpty>No frameworks found.</ComboboxEmpty>
          <ComboboxList>
            {(item: string) => (
              <ComboboxItem key={item} value={item}>
                {item}
              </ComboboxItem>
            )}
          </ComboboxList>
        </ComboboxContent>
      </Combobox>
    </div>
  )
}

Creatable

Let users add an option that isn't in the list. Control the items, value, and inputValue yourself: when the typed query has no exact match, append a synthetic "create" item, and in onValueChange detect it to add the new entry to your data and select it. Here each created label is added to a multi-select chip field.

'use client'

import * as React from 'react'
import {
  Combobox,
  ComboboxChips,
  ComboboxChip,
  ComboboxValue,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxList,
  ComboboxItem,
} from '@appica/ui-react/combobox'
import { Plus } from '@appica/icons-react'

interface Label {
  id: string
  value: string
  creatable?: string
}

const initialLabels: Label[] = [
  { id: 'bug', value: 'bug' },
  { id: 'documentation', value: 'documentation' },
  { id: 'enhancement', value: 'enhancement' },
  { id: 'help-wanted', value: 'help wanted' },
  { id: 'good-first-issue', value: 'good first issue' },
]

export default function ComboboxCreatable() {
  const [labels, setLabels] = React.useState<Label[]>(initialLabels)
  const [selected, setSelected] = React.useState<Label[]>([])
  const [query, setQuery] = React.useState('')

  const trimmed = query.trim()
  const lowered = trimmed.toLocaleLowerCase()
  const exactExists = labels.some((label) => label.value.trim().toLocaleLowerCase() === lowered)
  const items: Label[] =
    trimmed !== '' && !exactExists
      ? [...labels, { id: `create:${lowered}`, value: `Create "${trimmed}"`, creatable: trimmed }]
      : labels

  return (
    <div className="w-full max-w-70">
      <Combobox
        items={items}
        multiple
        value={selected}
        inputValue={query}
        onInputValueChange={setQuery}
        itemToStringLabel={(item) => (item as Label).value}
        onValueChange={(next) => {
          const list = next as Label[]
          const created = list.find((item) => item.creatable && !selected.some((s) => s.id === item.id))
          if (created?.creatable) {
            const label: Label = {
              id: created.creatable.toLocaleLowerCase().replace(/\s+/g, '-'),
              value: created.creatable,
            }
            setLabels((prev) => (prev.some((l) => l.id === label.id) ? prev : [...prev, label]))
            setSelected((prev) => [...prev, label])
            setQuery('')
            return
          }
          setSelected(list.filter((item) => !item.creatable))
          setQuery('')
        }}
      >
        <ComboboxChips placeholder="Add labels…">
          <ComboboxValue>
            {(value: Label[]) =>
              value.map((label) => (
                <ComboboxChip key={label.id} aria-label={label.value}>
                  {label.value}
                </ComboboxChip>
              ))
            }
          </ComboboxValue>
        </ComboboxChips>
        <ComboboxContent>
          <ComboboxEmpty>No labels found.</ComboboxEmpty>
          <ComboboxList>
            {(item: Label) =>
              item.creatable ? (
                <ComboboxItem key={item.id} value={item}>
                  <Plus data-icon="start" />
                  Create &ldquo;{item.creatable}&rdquo;
                </ComboboxItem>
              ) : (
                <ComboboxItem key={item.id} value={item}>
                  {item.value}
                </ComboboxItem>
              )
            }
          </ComboboxList>
        </ComboboxContent>
      </Combobox>
    </div>
  )
}

Controlled

Drive the selection yourself with value + onValueChange. The input's text is managed separately — control it too with inputValue + onInputValueChange when you need to.

Selected: —

'use client'

import * as React from 'react'
import {
  Combobox,
  ComboboxInput,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxList,
  ComboboxItem,
} from '@appica/ui-react/combobox'

const frameworks = ['Next.js', 'Remix', 'Astro', 'Nuxt.js', 'SvelteKit', 'SolidStart', 'Gatsby', 'Vite']

export default function ComboboxControlled() {
  const [value, setValue] = React.useState<string | null>(null)

  return (
    <div className="flex w-full max-w-70 flex-col gap-3">
      <Combobox items={frameworks} value={value} onValueChange={(v) => setValue(v as string | null)} clearable>
        <ComboboxInput placeholder="Search a framework" aria-label="Choose a framework" />
        <ComboboxContent>
          <ComboboxEmpty>No frameworks found.</ComboboxEmpty>
          <ComboboxList>
            {(item: string) => (
              <ComboboxItem key={item} value={item}>
                {item}
              </ComboboxItem>
            )}
          </ComboboxList>
        </ComboboxContent>
      </Combobox>
      <p className="text-foreground-muted text-sm">
        Selected: <span className="text-foreground font-medium">{value ?? '—'}</span>
      </p>
    </div>
  )
}

RTL

Every Appica UI component supports right-to-left layouts out of the box. Set the dir attribute on a container (commonly your <html> element) so CSS logical properties resolve correctly, and wrap your tree in DirectionProvider so direction-aware behavior — roving focus, popup placement, and the like — follows the same direction.

import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}

For setup details and caveats, see the RTL guide.

API reference

Combobox wraps Base UI's Combobox. Each part forwards every remaining prop to the matching Base UI primitive, so anything it accepts works here — the tables below list the Appica additions and the most common props. See the Base UI docs for the complete API.

Combobox

The root. Holds the data and the shared styling/behavior options; renders no DOM of its own.

Prop	Type	Default	Description
`items`	`readonly T[] \| { value, items }[]`	—	The data to filter. A flat array, or `{ value, items }` objects for grouped options.
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	Input height, popup radius, and item sizing.
`variant`	`'outline' \| 'soft'`	`'outline'`	Input appearance — bordered or filled.
`clearable`	`boolean`	`false`	Render a clear button inside the input when a value is present.
`icon`	`boolean`	`true`	Render a chevron button that toggles the popup.
`grid`	`boolean`	`false`	Lay options out as a navigable grid instead of a list.
`multiple`	`boolean`	`false`	Allow selecting several values; the value becomes an array.
`value`	`T \| T[] \| null`	—	Controlled selection. Pair with `onValueChange`.
`defaultValue`	`T \| T[] \| null`	—	Uncontrolled initial selection.
`onValueChange`	`(value, details) => void`	—	Fires when the selection changes.
`inputValue`	`string`	—	Controlled input text. Pair with `onInputValueChange`.
`onInputValueChange`	`(value, details) => void`	—	Fires as the typed text changes.
`itemToStringLabel`	`(item: T) => string`	—	For object items: the text the input shows and the filter matches against.
`itemToStringValue`	`(item: T) => string`	—	For object items: the string value reported for forms.
`mode`	`'list' \| 'inline' \| 'both' \| 'none'`	`'list'`	List filtering vs. inline autocompletion behavior.
`autoHighlight`	`boolean \| 'always'`	`false`	Highlight the first matching item as you type.
`disabled`	`boolean`	`false`	Disable the whole control.
`required`	`boolean`	`false`	Require a value before the form submits.
`name`	`string`	—	Field name submitted with a form.

ComboboxInput

The text field. Renders Base UI's Input inside an InputGroup, styled like Input.

Prop	Type	Default	Description
`startSlot`	`ReactNode`	—	Adornment rendered before the field, inside the input frame.
`endSlot`	`ReactNode`	—	Adornment rendered after the field, before the controls.
`placeholder`	`string`	`' '`	Placeholder text.
`disabled`	`boolean`	`false`	Disables the field and the clear/chevron buttons.
`aria-invalid`	`boolean \| 'true' \| 'false'`	—	Marks the error state; mirrored to `data-invalid` for styling.
`className`	`string`	—	Extra classes on the input group, merged via `tailwind-merge`.

Also forwards every native <input> prop (onChange, name, aria-*, ref, …).

ComboboxTrigger

A select-style trigger button (styled like Input) that shows the value via ComboboxValue and opens the popup. Use it — instead of ComboboxInput as the field — when the search input should live inside ComboboxContent.

Prop	Type	Default	Description
`startSlot`	`ReactNode`	—	Adornment before the value, inside the trigger frame.
`endSlot`	`ReactNode`	—	Adornment after the value, before the chevron.
`children`	`ReactNode`	—	The trigger content — typically a `ComboboxValue`.
`className`	`string`	—	Extra classes, merged via `tailwind-merge`.

Also forwards every native <button> prop (onClick, disabled, aria-*, ref, …).

ComboboxChips

The chip-based input for multiple selection — render it instead of ComboboxInput.

Prop	Type	Default	Description
`placeholder`	`string`	—	Placeholder for the inline text field.
`inputProps`	`object`	—	Props forwarded to the inner text `input`.
`children`	`ReactNode`	—	A `ComboboxValue` mapping selected values to `ComboboxChip`s.
`className`	`string`	—	Extra classes, merged via `tailwind-merge`.

ComboboxChip

One removable chip representing a selected value.

Prop	Type	Default	Description
`children`	`ReactNode`	—	The chip label; a remove (✕) button is added.
`className`	`string`	—	Extra classes, merged via `tailwind-merge`.

ComboboxContent

The portalled, auto-positioned popup wrapping the list. Accepts the shared floating props.

Prop	Type	Default	Description
`side`	`'top' \| 'right' \| 'bottom' \| 'left'`	`'bottom'`	Preferred side of the input to open on.
`align`	`'start' \| 'center' \| 'end'`	—	Alignment along that side.
`sideOffset`	`number`	`6`	Gap between the input and the popup.
`alignOffset`	`number`	—	Shift along the alignment axis.
`container`	`HTMLElement \| ref \| null`	—	Portal target — render the popup into a different node.
`keepMounted`	`boolean`	`false`	Keep the popup mounted in the DOM while closed.
`positionerProps`	`object`	—	Escape hatch for the positioner element (`style`, `render`, …).
`portalProps`	`object`	—	Escape hatch for the portal element (`style`, `render`, …).
`className`	`string`	—	Extra classes on the popup.

ComboboxList

The scrollable list container.

Prop	Type	Default	Description
`cols`	`number`	—	Items per row in grid mode (defaults to 2 when `grid` is set).
`children`	`ReactNode \| (item, index) => ReactNode`	—	A render function over the filtered items, or static `ComboboxItem`s.

ComboboxItem

One option in the list.

Prop	Type	Default	Description
`value`	`T`	—	The item this option represents; reported on selection.
`disabled`	`boolean`	`false`	Make the option unselectable.
`className`	`string`	—	Extra classes (e.g. `flex-1` to fill a grid cell).

ComboboxEmpty

Shown only when the filter matches nothing — otherwise it renders nothing.

Prop	Type	Default	Description
`children`	`ReactNode`	—	The empty-state message.
`className`	`string`	—	Extra classes, merged via `tailwind-merge`.

ComboboxGroup

Wraps one section of a grouped list. Pass the section's items so a nested ComboboxCollection can render them, and label it with a ComboboxLabel.

Prop	Type	Default	Description
`items`	`readonly T[]`	—	The group's items, consumed by `ComboboxCollection`.
`children`	`ReactNode`	—	A `ComboboxLabel` plus the group's items.
`className`	`string`	—	Extra classes, merged via `tailwind-merge`.

ComboboxLabel

The visible heading for a ComboboxGroup.

Prop	Type	Default	Description
`children`	`ReactNode`	—	The label text.
`className`	`string`	—	Extra classes, merged via `tailwind-merge`.

ComboboxCollection

Renders the items of the enclosing ComboboxGroup from a render function.

Prop	Type	Default	Description
`children`	`(item, index) => ReactNode`	—	Render function for each group item.

ComboboxValue

Renders the current value — typically a function child mapping the selected value(s) to chips or text.

Prop	Type	Default	Description
`children`	`ReactNode \| (value) => ReactNode`	—	Static content, or a render function of the value.

ComboboxSeparator

A thin divider between sections.

Prop	Type	Default	Description
`className`	`string`	—	Extra classes, merged via `tailwind-merge`.

Accessibility

The input has role="combobox"; the popup is a listbox (or grid when grid is set) and items are option/gridcell. Selection and active state are wired through aria-activedescendant.
↑/↓ move the highlight, Enter selects, Escape closes the popup, and typing filters the list. In multiple mode, Backspace in an empty field removes the last chip.
The clear and chevron buttons have aria-labels (Clear selection, Toggle popup) and become disabled when the input is disabled; chip remove buttons are labelled Remove.
Always give ComboboxInput (or ComboboxChips) a visible label or an aria-label.
aria-invalid on the input is bridged to data-invalid so the error state styles with or without a wrapping Field.
Popup enter/exit transitions are skipped when the user prefers reduced motion.

Actions & Inputs

Data Display

Decoration & Effects

Layout

Menus

Navigation

Overlays

Status & Feedback

Combobox

Usage

Examples

Variants

Sizes

Clearable & chevron

Disabled & error states

Start & end slots

Country select

User select

Grouped options

Grid layout

Multiple selection

Creatable

Controlled

RTL

API reference

Combobox

ComboboxInput

ComboboxTrigger

ComboboxChips

ComboboxChip

ComboboxContent

ComboboxList

ComboboxItem

ComboboxEmpty

ComboboxGroup

ComboboxLabel

ComboboxCollection

ComboboxValue

ComboboxSeparator

Accessibility

Combobox

Usage

Examples

Variants

Sizes

Clearable & chevron

Disabled & error states

Start & end slots

Country select

Input inside popup and custom scroll

User select

Grouped options

Grid layout

Multiple selection

Creatable

Controlled

RTL

API reference

Combobox

ComboboxInput

ComboboxTrigger

ComboboxChips

ComboboxChip

ComboboxContent

ComboboxList

ComboboxItem

ComboboxEmpty

ComboboxGroup

ComboboxLabel

ComboboxCollection

ComboboxValue

ComboboxSeparator

Accessibility