Combobox

Combobox is a text field over a list: typing filters it (case and accents ignored), the arrows move through it and Enter picks. The field wears the kit's Input box; the list is the menu plate with 44 px rows. multiple prints the choices as removable chips; loading says "Searching…"; an empty list says what was not found. inline prints the list in place under the field, as the docs search does in its dialog.

Example#

Usage#

Use a combobox for a long list someone searches rather than scans: people, projects, tags, the docs search. Typing filters the list; the arrows move through it and Enter picks.

• Filtering ignores case and accents by default; pass filter for your own rule.
• Many values. multiple prints the choices as removable chips, and Backspace removes the last.
• Waiting and nothing found. loading says "Searching…" while results arrive; emptyText says what was not found, with the query.
• In place. inline prints the list under the field instead of in a popup, as the docs search does inside its dialog.
• Short lists are a Select or a RadioGroup; a combobox only earns its keystrokes past about fifteen options.

Recipe: reviewers in groups, several at once#

"use client";
import { Combobox } from "@maxgrits/overprint-react/combobox";

const PEOPLE = [
  { label: "Studio", items: [{ label: "Jordan Reyes", description: "Design" }, { label: "Sam Okafor", description: "Build" }] },
  { label: "Clients", items: [{ label: "Dana Whitfield", description: "Fernlight" }, { label: "Mei Tanaka", description: "Pebblepath" }] },
];

export function Reviewers() {
  return (
    <Combobox
      items={PEOPLE}
      multiple
      itemToString={(p) => p.label}
      aria-label="Reviewers"
      placeholder="Add a reviewer"
      emptyText="No one by that name yet"
    />
  );
}

Groups print their labels as list headings; with multiple, each pick becomes a chip in the field, and Backspace removes the last one. Items with a description show it under the name, so a server component can pass plain objects.

Anatomy#

Volume#

Reading layer: identical at every volume, popup included.

• Quiet

  Docs, forms, legal and long reads. Flat inks, no art in motion.

• Studio

  The site default. Art on its own plates, one display moment per view.

• Press

  Hero moments, covers and campaigns. Halftone fields and the second ink.

• Rave

  Launches, posters and the 404. Every ink, and the words still win.

Content#

• The placeholder says what can be found: "Find a person", "Search the docs".
• The empty state repeats the query and offers a way out: "No matches for "pebl". Check the spelling or browse all projects."
• Items lead with the words people type; a description line can add the detail that tells two similar items apart.

Do and don't#

Accessibility#

• The APG combobox through Base UI: Down and Up open and move, Enter selects, Escape closes, typing filters.
• A polite live region counts the results.
• Name it with a Field label or aria-label. The list portals with the field's scope.

The colour pairs it prints, with their contrast on both papers:

Props#

Tokens#

Changelog#