Combobox

function App() {
const [value, setValue] = useState<string | null>("Apple");

return (

<Combobox value={value} onValueChange={(v) => setValue(v as any)} items={fruits}>  
<Combobox.TriggerInput placeholder="Please select" />
<Combobox.Content>
<Combobox.Empty />
<Combobox.List>
{(item: string) => (
<Combobox.Item key={item} value={item}>
{item}
</Combobox.Item>
)}
</Combobox.List>
</Combobox.Content>
</Combobox>  
);
}

const fruits = [
"Apple",
"Orange",
"Banana",
"Grape",
"Strawberry",
"Blueberry",
"Cherry",
"Watermelon",
"Peach",
"Pear",
];

Installation

Barrel

import { Combobox } from "@cloudflare/kumo";

Granular

import { Combobox } from "@cloudflare/kumo/components/combobox";

Sizes

The Combobox supports four size variants that match the Input component: xs, sm, base (default), and lg.

<Combobox size="sm" items={fruits} value={value} onValueChange={setValue}>
<Combobox.TriggerInput placeholder="Select fruit" />
<Combobox.Content>
  <Combobox.Empty />
  <Combobox.List>
    {(item) => (
      <Combobox.Item key={item} value={item}>
        {item}
      </Combobox.Item>
    )}
  </Combobox.List>
</Combobox.Content>
</Combobox>

Size also applies to TriggerValue (searchable inside variant):

<Combobox size="sm" items={languages} value={value} onValueChange={setValue}>
<Combobox.TriggerValue className="w-[160px]" />
<Combobox.Content>
  <Combobox.Input placeholder="Search" />
  <Combobox.Empty />
  <Combobox.List>
    {(item) => (
      <Combobox.Item key={item.value} value={item}>
        {item.emoji} {item.label}
      </Combobox.Item>
    )}
  </Combobox.List>
</Combobox.Content>
</Combobox>

Searchable Item (Inside)

A searchable select component inside popup that allows users to filter and select.

function App() {
const [value, setValue] = useState<Language | null>(languages[0]);

return (

<Combobox
value={value}
onValueChange={(v) => setValue(v)}
items={languages} >
<Combobox.TriggerValue className="w-[200px]" />
<Combobox.Content>
<Combobox.Input /> // Add this to make item searchable
<Combobox.Empty />
<Combobox.List>
{(item: Language) => (
<Combobox.Item key={item.value} value={item}>
{item.emoji} {item.label}
</Combobox.Item>
)}
</Combobox.List>
</Combobox.Content>
</Combobox>
);
}

interface Language {
value: string;
label: string;
emoji: string;
}

const languages: Language[] = [
{ value: "en", label: "English", emoji: "🇬🇧" },
{ value: "fr", label: "French", emoji: "🇫🇷" },
{ value: "de", label: "German", emoji: "🇩🇪" },
{ value: "es", label: "Spanish", emoji: "🇪🇸" },
{ value: "it", label: "Italian", emoji: "🇮🇹" },
{ value: "pt", label: "Portuguese", emoji: "🇵🇹" },
];

Grouped

Group items into categories using the Group and GroupLabel components.

function App() {
const [value, setValue] = useState<string | null>("singapore");

return (

<Combobox value={value} onValueChange={(v) => setValue(v as any)} items={server}>
<Combobox.TriggerInput className="w-[200px]" placeholder="Select server" />
<Combobox.Content>
<Combobox.Empty />
<Combobox.List>
{(group: ServerLocationGroup) => (
<Combobox.Group key={group.value} items={group.items}>
<Combobox.GroupLabel>{group.value}</Combobox.GroupLabel>
<Combobox.Collection>
{(item: ServerLocation) => {
return (
<Combobox.Item key={item.value} value={item}>
{item.label}
</Combobox.Item>
);
}}
</Combobox.Collection>
</Combobox.Group>
)}
</Combobox.List>
</Combobox.Content>
</Combobox>  
)
}

const server = [
{
value: "Asia",
items: [
{ label: "Japan", value: "japan" },
{ label: "China", value: "china" },
{ label: "Singapore", value: "singapore" },
],
},
{
value: "Europe",
items: [
{ label: "Germany", value: "germany" },
{ label: "France", value: "france" },
{ label: "Italy", value: "italy" },
],
},
];

interface ServerLocation {
label: string;
value: string;
}

interface ServerLocationGroup {
value: string;
items: ServerLocation[];
}

Multiple

Allow users to select multiple options from the list.

<Combobox
value={value}
onValueChange={setValue}
items={bots}
isItemEqualToValue={(bot, selected) => bot.value === selected.value}
multiple
>
<Combobox.TriggerMultipleWithInput
  className="w-[400px]"
  placeholder="Select bots"
  renderItem={(selected) => (
    <Combobox.Chip key={selected.value}>
      {selected.label}
    </Combobox.Chip>
  )}
  inputSide="right"
/>
<Combobox.Content>
  <Combobox.Empty />
  <Combobox.List>
    {(item) => (
      <Combobox.Item key={item.value} value={item}>
        <Text>{item.label}</Text>
        <Text variant="secondary">{item.author}</Text>
      </Combobox.Item>
    )}
  </Combobox.List>
</Combobox.Content>
</Combobox>

With Field

Add label and description using the built-in Field wrapper.

Database

Select your preferred database

<Combobox
items={items}
value={value}
onValueChange={setValue}
label="Database"
description="Select your preferred database"
>
<Combobox.TriggerInput placeholder="Select database" />
<Combobox.Content>
  <Combobox.Empty />
  <Combobox.List>
    {(item) => (
      <Combobox.Item key={item.value} value={item}>
        {item.label}
      </Combobox.Item>
    )}
  </Combobox.List>
</Combobox.Content>
</Combobox>

Error State

Display validation errors with the error prop.

Database

Please select a database

<Combobox
items={items}
value={value}
onValueChange={setValue}
label="Database"
error={{ message: "Please select a database", match: true }}
>
<Combobox.TriggerInput placeholder="Select database" />
<Combobox.Content>
  <Combobox.Empty />
  <Combobox.List>
    {(item) => (
      <Combobox.Item key={item.value} value={item}>
        {item.label}
      </Combobox.Item>
    )}
  </Combobox.List>
</Combobox.Content>
</Combobox>

By default, Combobox.Content has a max height of 24rem (384px) or the available viewport space, whichever is smaller. The dropdown scrolls automatically when content exceeds this height.

To customize the max height, pass a className to Combobox.Content:

// Shorter dropdown (200px)
<Combobox.Content className="max-h-[200px]">

// Taller dropdown (500px)

<Combobox.Content className="max-h-[500px]">

// Use Tailwind presets

<Combobox.Content className="max-h-64">  // 256px
<Combobox.Content className="max-h-96">  // 384px (same as default)

API Reference

Root component for the searchable select.

Prop	Type	Default	Description
size	`"xs" \| "sm" \| "base" \| "lg"`	`"base"`	Size of the combobox trigger. Matches Input component sizes. - `"xs"` — Extra small for compact UIs (h-5 / 20px) - `"sm"` — Small for secondary fields (h-6.5 / 26px) - `"base"` — Default size (h-9 / 36px) - `"lg"` — Large for prominent fields (h-10 / 40px)
inputSide	`"right" \| "top"`	`"right"`	Position of the text input relative to chips in multi-select mode. - `"right"` — Input inline to the right of chips - `"top"` — Input above chips
items*	`T[]`	-	Array of items to display in the dropdown
value	`T \| T[]`	-	Currently selected value(s)
children	`ReactNode`	-	Combobox content (trigger, content, items)
className	`string`	-	Additional CSS classes
label	`ReactNode`	-	Label content for the combobox (enables Field wrapper) - can be a string or any React node
required	`boolean`	-	Whether the combobox is required
labelTooltip	`ReactNode`	-	Tooltip content to display next to the label via an info icon
description	`ReactNode`	-	Helper text displayed below the combobox
error	`string \| object`	-	Error message or validation error object
onValueChange	`(value: T \| T[]) => void`	-	Callback when selection changes
multiple	`boolean`	-	Allow multiple selections
isItemEqualToValue	`(item: T, value: T) => boolean`	-	Custom equality function for comparing items

Combobox.Content

Dropdown container for the list.

Prop	Type	Default
className	`string`	-
align	`ComboboxBase.Positioner.Props["align"]`	-
alignOffset	`ComboboxBase.Positioner.Props["alignOffset"]`	-
side	`ComboboxBase.Positioner.Props["side"]`	-
sideOffset	`ComboboxBase.Positioner.Props["sideOffset"]`	-

Combobox.Item

Individual selectable option.

Prop	Type	Default

No component-specific props. Accepts standard HTML attributes.

Additional Sub-components

Combobox.TriggerInput - Single-select input trigger
Combobox.TriggerValue - Button trigger showing selected value
Combobox.TriggerMultipleWithInput - Multi-select with chips
Combobox.Input - Search input inside dropdown
Combobox.List - List container with render prop
Combobox.Group - Group container for categorized items
Combobox.GroupLabel - Header label for a group
Combobox.Collection - Items container within a group
Combobox.Chip - Selected item chip
Combobox.Empty - Empty state message