Combobox

A field you can type into and also choose from. The text filters the list — and, unless you say otherwise, can become the value itself.

import { Combobox } from 'neba';

<Combobox
  label="Framework"
  placeholder="Search or type your own"
  items={[
    { value: 'react', label: 'React' },
    { value: 'vue', label: 'Vue' }
  ]}
/>;

Props

Prop	Type	Default	Description
variantshared	'solid' | 'outline' | 'text'	'outline'	Weight of the surface. The same shell as a TextField, so the two are indistinguishable in a form
sizeshared	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'	Height and type scale. With multiple it becomes a minimum, because the field grows as the chips wrap
colorshared	'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info'	'primary'	Semantic colour role. The surface is white, so it reaches the edge, the focus ring and the chips
densityshared	'default' | 'compact'	'default'	Padding only — never the height, never the type scale
elevationshared	0 | 1 | 2 | 3	0	Drop shadow depth of the field. The popup carries its own
items *	readonly ComboboxOption[]	—	The options, as an array of { value, label?, disabled? } — label is a string, not a ReactNode
multiple	boolean	false	Whether more than one value may be held. The chosen ones become chips inside the field
value	string | number | (string | number)[] | null	—	The chosen value — an array when multiple. Use with onValueChange for a controlled combobox
defaultValue	string | number | (string | number)[] | null	—	The initial value, for an uncontrolled combobox
onValueChange	(value) => void	—	Called when the chosen value changes
onInputValueChange	(inputValue: string) => void	—	Called as the text in the input changes — the filter query, not the value
allowCustom	boolean	true	Whether a value the list does not contain may be committed. The typed text is offered as its own row at the end of the list — what separates this from a searchable select
customLabel	(query: string) => ReactNode	Add “…”	What that row says
clearable	boolean	false	Shows a × that empties the field. A field that can be cleared in one click can be emptied by accident
emptyMessage	ReactNode	'No matches'	Shown in the popup when nothing matches and no value may be added
limit	number	-1	The most rows the list will show at once. -1 is all of them
placeholder	string	—	Shown in the input while nothing is typed
label	ReactNode	—	The label, wired to the control by Base UI's Field
description	ReactNode	—	Helper text
error	ReactNode	—	Error message. Its presence turns the control invalid and re-points the colour family at danger
invalid	boolean	!!error	Forces the invalid state without a message, for when a form library owns validity
startIcon	ReactNode	—	Content before the input
fullWidth	boolean	false	Stretches to the width of the container
removeLabel	(label: string) => string	Remove …	Accessible name of a chip's remove button. Receives the chip's label
clearLabel	string	'Clear'	Accessible name of the clear button
name	string	—	Identifies the field when a form is submitted
readOnly	boolean	false	Shown but not changeable. Keeps its colour and edge, drains the saturation
disabled	boolean	false	Unavailable. Drops the colour family for neutral grey

Options are data

The same shape Select takes, with one difference:

interface ComboboxOption {
  value: string | number;
  label?: string; // a string, not a ReactNode
  disabled?: boolean;
}

label is a string here because the filter types against it and the input writes it out, and neither of those can be done to an element. Values stay strings and numbers — a combobox is a form control and its value is what gets submitted.

Examples

Multiple

The chosen values become Chips inside the field, and the input goes on filtering after each one, so a set of tags is built without the field ever closing. Backspace on an empty input reaches back for the last chip.

import { useState } from 'react';
import { Combobox } from 'neba';

const LABELS = [
  { value: 'bug', label: 'bug' },
  { value: 'docs', label: 'documentation' },
  { value: 'dx', label: 'developer experience' },
  { value: 'good-first', label: 'good first issue' },
  { value: 'perf', label: 'performance' }
];

export default function ComboboxMultiple() {
  const [labels, setLabels] = useState<(string | number)[]>(['bug']);

  return (
    <div className="flex w-full max-w-md flex-col gap-3">
      <Combobox
        multiple
        fullWidth
        items={LABELS}
        label="Labels"
        placeholder="Add a label"
        description="Type something the list does not have and the last row offers it."
        value={labels}
        onValueChange={setLabels}
      />
      <p className="text-xs text-(--neba-muted-fg)">
        {labels.length > 0 ? labels.join(', ') : 'nothing chosen'}
      </p>
    </div>
  );
}

A value the list does not have

This is what separates a combobox from a searchable select, and it is on by default.

The typed text is offered as its own row at the end of the list rather than committed quietly on blur. That is deliberate: a field that turns a half-finished word into a value the moment focus leaves is a field that invents data. Making it a row means Enter, a click and the arrow keys all reach it the way they reach every other row, and a screen reader announces it as one more option.

The first match lights up as you type, so it still takes one key: type something the list has and Enter picks it, type something it does not and Enter adds it.

Turn it off with allowCustom={false} for a field whose values are a closed set — then emptyMessage is what a fruitless search says.

import { Combobox } from 'neba';

const TIMEZONES = [
  { value: 'Asia/Seoul', label: 'Asia/Seoul' },
  { value: 'Asia/Tokyo', label: 'Asia/Tokyo' },
  { value: 'Europe/Berlin', label: 'Europe/Berlin' },
  { value: 'America/New_York', label: 'America/New_York' }
];

export default function ComboboxCustom() {
  return (
    <div className="flex flex-wrap items-start gap-4">
      <Combobox
        items={TIMEZONES}
        label="Anything goes"
        placeholder="Type a timezone"
        customLabel={(query) => `Use “${query}” anyway`}
        description="A typed value is offered as the last row."
      />
      <Combobox
        items={TIMEZONES}
        allowCustom={false}
        label="Closed set"
        placeholder="Pick a timezone"
        emptyMessage="No such timezone."
        description="Only what the list holds."
      />
    </div>
  );
}

Variants

The same three weights a TextField has, drawn on the same shell.

import { Combobox } from 'neba';

const ITEMS = [
  { value: 'sans', label: 'Sans-serif' },
  { value: 'serif', label: 'Serif' },
  { value: 'mono', label: 'Monospace' }
];

export default function ComboboxVariants() {
  return (
    <div className="flex flex-wrap items-end gap-4">
      <Combobox items={ITEMS} variant="solid" label="Solid" defaultValue="sans" />
      <Combobox items={ITEMS} variant="outline" label="Outline" defaultValue="sans" />
      <Combobox items={ITEMS} variant="text" label="Text" defaultValue="sans" />
    </div>
  );
}

Sizes

A chip inside the field sits one step down the control ladder, and the field's padding is what is left over — so a single-row combobox is exactly as tall as the field beside it. With multiple the field grows as the chips wrap; it never has a fixed height.

import { Combobox } from 'neba';

const SIZES = ['xs', 'sm', 'md', 'lg', 'xl'] as const;

const ITEMS = [
  { value: 'day', label: 'Day' },
  { value: 'week', label: 'Week' },
  { value: 'month', label: 'Month' }
];

export default function ComboboxSizes() {
  return (
    <div className="flex flex-col gap-3">
      <div className="flex flex-wrap items-end gap-3">
        {SIZES.map((size) => (
          <Combobox key={size} items={ITEMS} size={size} defaultValue="week" />
        ))}
      </div>
      <div className="flex flex-wrap items-end gap-3">
        {SIZES.map((size) => (
          <Combobox key={size} multiple items={ITEMS} size={size} defaultValue={['week']} />
        ))}
      </div>
    </div>
  );
}

States

import { Combobox } from 'neba';

const ITEMS = [
  { value: 'starter', label: 'Starter' },
  { value: 'team', label: 'Team' }
];

export default function ComboboxStates() {
  return (
    <div className="flex flex-wrap items-start gap-4">
      <Combobox items={ITEMS} label="Read-only" readOnly defaultValue="team" />
      <Combobox items={ITEMS} label="Disabled" disabled defaultValue="team" />
      <Combobox items={ITEMS} label="Plan" placeholder="Pick one" error="Choose a plan." />
      <Combobox
        multiple
        items={ITEMS}
        label="Read-only tags"
        readOnly
        defaultValue={['starter', 'team']}
      />
    </div>
  );
}

The popup

Identical to Select's, because a combobox's list and a select's list are the same list: a floating surface at elevation 3, portalled to the end of <body>, with neba-portal on the positioner as a hook for a host that scoped its CSS reset to a subtree.

Accessibility

• Base UI owns the filtering and its collator, the popup's positioning and flipping, the combobox/listbox wiring, arrow-key navigation across both the list and the chips, and the hidden input that makes the field submit with a form.
• label becomes the accessible name.
• A disabled option stays in the list and reports aria-disabled — the option exists, it just cannot be picked.
• Each chip's remove button is named through removeLabel, which receives the chip's own label so the button says Remove documentation rather than Remove.