Combobox

A searchable input for choosing one or more values.

Default

Type to filter. The first match is highlighted, so Enter selects it without a click. ComboboxEmpty shows when nothing matches.

Transfer to agent

import {
  Combobox,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxItem,
  ComboboxList,
  ComboboxPopup,
  Field,
  FieldLabel,
} from "@smallest-inc/ui";

const agents = [
  "Appointment booking",
  "Billing support",
  "Collections reminder",
  "Customer survey",
  "Lead qualification",
  "Order status",
  "Front desk",
];

export default function ComboboxDefault() {
  return (
    <Field className="w-full max-w-xs">
      <FieldLabel>Transfer to agent</FieldLabel>
      <Combobox items={agents}>
        <ComboboxInput placeholder="Search agents" className="w-full" />
        <ComboboxPopup>
          <ComboboxEmpty>No agents found.</ComboboxEmpty>
          <ComboboxList>
            {(agent: string) => (
              <ComboboxItem key={agent} value={agent}>
                {agent}
              </ComboboxItem>
            )}
          </ComboboxList>
        </ComboboxPopup>
      </Combobox>
    </Field>
  );
}

Sizes

The default size is sm (36px). md is 40px.

import {
  Combobox,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxItem,
  ComboboxList,
  ComboboxPopup,
} from "@smallest-inc/ui";

const languages = ["English", "Hindi", "Spanish", "French", "German", "Japanese"];

export default function ComboboxSizes() {
  return (
    <div className="flex w-full max-w-xs flex-col gap-4">
      {(["sm", "md"] as const).map((size) => (
        <Combobox key={size} items={languages}>
          <ComboboxInput size={size} placeholder="Search languages" aria-label="Language" className="w-full" />
          <ComboboxPopup>
            <ComboboxEmpty>No languages found.</ComboboxEmpty>
            <ComboboxList>
              {(language: string) => (
                <ComboboxItem key={language} value={language}>
                  {language}
                </ComboboxItem>
              )}
            </ComboboxList>
          </ComboboxPopup>
        </Combobox>
      ))}
    </div>
  );
}

Variants

Primary is a flat neutral-100 field and is the default. Secondary is white with shadow-sm, for tinted panels.

import {
  Combobox,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxItem,
  ComboboxList,
  ComboboxPopup,
} from "@smallest-inc/ui";

const languages = ["English", "Hindi", "Spanish", "French", "German", "Japanese"];

export default function ComboboxVariants() {
  return (
    <div className="flex w-full max-w-xs flex-col gap-4">
      {(["primary", "secondary"] as const).map((variant) => (
        <Combobox key={variant} items={languages}>
          <ComboboxInput variant={variant} placeholder="Search languages" aria-label="Language" className="w-full" />
          <ComboboxPopup>
            <ComboboxEmpty>No languages found.</ComboboxEmpty>
            <ComboboxList>
              {(language: string) => (
                <ComboboxItem key={language} value={language}>
                  {language}
                </ComboboxItem>
              )}
            </ComboboxList>
          </ComboboxPopup>
        </Combobox>
      ))}
    </div>
  );
}

Clear

Set showClear to swap the chevron for a clear button once a value is chosen.

Voice

import {
  Combobox,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxItem,
  ComboboxList,
  ComboboxPopup,
  Field,
  FieldLabel,
} from "@smallest-inc/ui";

const voices = ["Aria", "Arjun", "Chloe", "Diego", "Emma", "Kai", "Meera", "Rohan", "Sofia"];

export default function ComboboxClear() {
  return (
    <Field className="w-full max-w-xs">
      <FieldLabel>Voice</FieldLabel>
      <Combobox items={voices} defaultValue="Meera">
        <ComboboxInput placeholder="Search voices" showClear className="w-full" />
        <ComboboxPopup>
          <ComboboxEmpty>No voices found.</ComboboxEmpty>
          <ComboboxList>
            {(voice: string) => (
              <ComboboxItem key={voice} value={voice}>
                {voice}
              </ComboboxItem>
            )}
          </ComboboxList>
        </ComboboxPopup>
      </Combobox>
    </Field>
  );
}

Groups

Pass grouped items and render each as a ComboboxGroup with a ComboboxLabel. Labels hide while the input has a query.

Model

import {
  Combobox,
  ComboboxCollection,
  ComboboxEmpty,
  ComboboxGroup,
  ComboboxInput,
  ComboboxItem,
  ComboboxLabel,
  ComboboxList,
  ComboboxPopup,
  Field,
  FieldLabel,
} from "@smallest-inc/ui";

const providers = [
  { label: "OpenAI", items: ["GPT-4.1", "GPT-4.1 mini", "o3"] },
  { label: "Anthropic", items: ["Claude Sonnet", "Claude Haiku"] },
  { label: "Google", items: ["Gemini 2.5 Pro", "Gemini 2.5 Flash"] },
];

export default function ComboboxGroups() {
  return (
    <Field className="w-full max-w-xs">
      <FieldLabel>Model</FieldLabel>
      <Combobox items={providers}>
        <ComboboxInput placeholder="Search models" className="w-full" />
        <ComboboxPopup>
          <ComboboxEmpty>No models found.</ComboboxEmpty>
          <ComboboxList>
            {(provider: (typeof providers)[number]) => (
              <ComboboxGroup
                key={provider.label}
                items={provider.items}
                className="[&+&]:mt-1.5 [&+&]:border-t [&+&]:border-neutral-150 [&+&]:pt-1.5"
              >
                <ComboboxLabel>{provider.label}</ComboboxLabel>
                <ComboboxCollection>
                  {(model: string) => (
                    <ComboboxItem key={model} value={model}>
                      {model}
                    </ComboboxItem>
                  )}
                </ComboboxCollection>
              </ComboboxGroup>
            )}
          </ComboboxList>
        </ComboboxPopup>
      </Combobox>
    </Field>
  );
}

Multiple

Set multiple and render values as ComboboxChip inside ComboboxChips. Anchor the popup to the chips with useComboboxAnchor.

Call tags

Escalated

Refund

import {
  Combobox,
  ComboboxChip,
  ComboboxChips,
  ComboboxChipsInput,
  ComboboxEmpty,
  ComboboxItem,
  ComboboxList,
  ComboboxPopup,
  ComboboxValue,
  Field,
  FieldLabel,
  useComboboxAnchor,
} from "@smallest-inc/ui";

const tags = ["Billing", "Churn risk", "Complaint", "Escalated", "Follow-up", "Refund", "Renewal", "VIP"];

export default function ComboboxMultiple() {
  const anchor = useComboboxAnchor();

  return (
    <Field className="w-full max-w-sm">
      <FieldLabel>Call tags</FieldLabel>
      <Combobox multiple items={tags} defaultValue={["Escalated", "Refund"]}>
        <ComboboxChips ref={anchor}>
          <ComboboxValue>
            {(values: string[]) =>
              values.map((tag) => (
                <ComboboxChip key={tag} variant="md">
                  {tag}
                </ComboboxChip>
              ))
            }
          </ComboboxValue>
          <ComboboxChipsInput placeholder="Add tag" />
        </ComboboxChips>
        <ComboboxPopup anchor={anchor}>
          <ComboboxEmpty>No tags found.</ComboboxEmpty>
          <ComboboxList>
            {(tag: string) => (
              <ComboboxItem key={tag} value={tag}>
                {tag}
              </ComboboxItem>
            )}
          </ComboboxList>
        </ComboboxPopup>
      </Combobox>
    </Field>
  );
}

Selected first

Wrap the list in ComboboxSelectionGroups to show chosen options above the rest, with optional section labels.

Supported languages

English

Hindi

import { useState } from "react";
import {
  Combobox,
  ComboboxChip,
  ComboboxChips,
  ComboboxChipsInput,
  ComboboxEmpty,
  ComboboxItem,
  ComboboxList,
  ComboboxPopup,
  ComboboxSelectionGroups,
  ComboboxValue,
  Field,
  FieldLabel,
  useComboboxAnchor,
} from "@smallest-inc/ui";

const languages = ["Arabic", "Bengali", "English", "French", "German", "Hindi", "Japanese", "Spanish", "Tamil"];

export default function ComboboxSelectedFirst() {
  const anchor = useComboboxAnchor();
  const [value, setValue] = useState(["English", "Hindi"]);

  return (
    <Field className="w-full max-w-sm">
      <FieldLabel>Supported languages</FieldLabel>
      <Combobox multiple items={languages} value={value} onValueChange={setValue}>
        <ComboboxChips ref={anchor}>
          <ComboboxValue>
            {(values: string[]) =>
              values.map((language) => (
                <ComboboxChip key={language} variant="md">
                  {language}
                </ComboboxChip>
              ))
            }
          </ComboboxValue>
          <ComboboxChipsInput placeholder="Add language" />
        </ComboboxChips>
        <ComboboxPopup anchor={anchor}>
          <ComboboxEmpty>No languages found.</ComboboxEmpty>
          <ComboboxList>
            <ComboboxSelectionGroups selected={value} selectedLabel="Selected" unselectedLabel="All languages">
              {(language: string) => (
                <ComboboxItem key={language} value={language}>
                  {language}
                </ComboboxItem>
              )}
            </ComboboxSelectionGroups>
          </ComboboxList>
        </ComboboxPopup>
      </Combobox>
    </Field>
  );
}

Disabled

Set disabled on both Combobox and ComboboxInput so the field and its chevron stop responding.

import {
  Combobox,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxItem,
  ComboboxList,
  ComboboxPopup,
} from "@smallest-inc/ui";

const numbers = ["+1 415 555 0123", "+44 20 7946 0958", "+91 80 4567 8901"];

export default function ComboboxDisabled() {
  return (
    <div className="w-full max-w-xs">
      <Combobox items={numbers} defaultValue="+1 415 555 0123" disabled>
        <ComboboxInput aria-label="Caller ID" disabled className="w-full" />
        <ComboboxPopup>
          <ComboboxEmpty>No numbers found.</ComboboxEmpty>
          <ComboboxList>
            {(number: string) => (
              <ComboboxItem key={number} value={number}>
                {number}
              </ComboboxItem>
            )}
          </ComboboxList>
        </ComboboxPopup>
      </Combobox>
    </div>
  );
}

Best practices

When to use

Use when a value comes from a known list and typing to filter that list is useful, such as agents, models, or tags.
Use Select for a short fixed list and Input for genuinely free-form values.

Behavior

Filter from ComboboxInput or ComboboxChipsInput. The popup lists matches only; do not add a separate search field inside it.
The first filtered match is highlighted by default, so Enter selects it without a click, like Command search.
Always include ComboboxEmpty with a specific message, like “No agents found.”. When nothing matches, the list hides and that single row shows.
Section labels hide while the input has a filter query.
Use showClear when clearing the value is a normal action; it replaces the chevron once a value is set.
For multiple values, render ComboboxChip inside ComboboxChips and anchor ComboboxPopup to the chips with useComboboxAnchor.
Wrap the list in ComboboxSelectionGroups when chosen options should stay above the rest.

Accessibility

Keep the input name stable (FieldLabel or aria-label) and return focus to it when the popup closes.
Set disabled on both Combobox and ComboboxInput so the field and its chevron are both inert.

PreviousColor Picker NextCommand