Searchable Select

InstallCopy Anchor Link

pnpm exec vegastack-design verify searchable-select

pnpm dlx shadcn@4.21.0 add @vegastack/searchable-select

UsageCopy Anchor Link

import { SearchableSelect } from "@/components/ui/searchable-select";

const [project, setProject] = React.useState<Project | null>(null);

<SearchableSelect
  items={projects}
  value={project}
  onValueChange={setProject}
  itemToKey={(p) => p.id}
  itemToStringLabel={(p) => p.name}
  searchLabel="Search projects"
  placeholder="Select project"
/>;

SearchableSelect is the one preset for "a Select, but the list is too long to scroll". It is controlled by the item itself, not by an id: pass the selected item as value, and onValueChange hands you back an item (or null when the clear control is used). Give it isItemEqualToValue when the value is not the same object reference as the entry in items.

Use it instead of restating the recipe: CountrySelect and RegionSelect are both thin wrappers over it, and a third data-fed picker should be too.

Reach for a plain Select when the option set is short and fixed, and for Combobox directly when you need free text, suggestions, or multi-select chips.

AnatomyCopy Anchor Link

Searchable Select exports the picker and PersonOption, the standard person row it draws from itemToSecondaryLabel: an avatar, then the name on the first line and a smaller muted email on the second — stacked, never inline. It is the standard for every person list — pickers, filter facets and menus such as a row's Assign › submenu — and a popup that lists people is at least 18rem wide (min-w-72) so neither line truncates. Every exported part, with the data-slot it renders (generated from the canonical source):

ExamplesCopy Anchor Link

AnatomyCopy Anchor Link

Three parts, and one rule that shapes the layout:

<div className="relative w-full">   // the wrapper
  <Combobox.Trigger render={<Button variant="outline" className="w-full pe-9" />}>
    <ComboboxValue />               // the selected face, or the muted placeholder
  </Combobox.Trigger>
  <ComboboxContent className="w-(--anchor-width) p-0">
    <ComboboxInput showTrigger={false} /> // the panel-search row, inside the popup
    <ComboboxEmpty />
    <ComboboxList>{…ComboboxItem per item, check on the selected one…}</ComboboxList>
  </ComboboxContent>
  {/* chevron, OR the clear control when `clearable` and a value is set */}
</div>

The rule: an interactive control may not contain another one, so the clear control can never live inside the trigger button. Both it and the chevron are siblings positioned inside the wrapper, and they share one trailing reserve — so the trigger's text box does not move when a value is set.

The trigger is w-full, like every other form control. Constrain it with a parent (<div className="max-w-xs">), never with a width of its own; the panel matches the trigger width through --anchor-width.

Selected and emptyCopy Anchor Link

With a value set the trigger shows it and the matching row carries a check; with none it shows the muted placeholder and carries data-placeholder.

ClearableCopy Anchor Link

clearable swaps the chevron for a clear control while a value is set. It reports null, which is the same code path every other selection uses.

Inside a FieldCopy Anchor Link

Inside a Field the trigger is named by FieldLabel — not by its value — described by the rendered FieldDescription and FieldError, and marked invalid from the Field. name submits the selected item's itemToKey with a form, and required blocks the submit while nothing is selected.

Inline in a rowCopy Anchor Link

For a picker inside a table row or a toolbar, size="sm" matches Select size="sm" and DatePicker size="sm", and variant="ghost" sizes the trigger to its content with no border at rest. contentClassName widens the panel past a narrow trigger. Clearing returns focus to the trigger.

For a picker that lives in a chip row — a customer or project pill on a record — renderTrigger replaces the whole trigger with your own element, built from the current selection. The field chrome (border, chevron, clear control) goes with it; the popup, search, keyboard and value contract stay. The element must hold a ref and take button props.

<SearchableSelect
  items={customers}
  value={customer}
  onValueChange={setCustomer}
  itemToKey={(c) => c.id}
  itemToStringLabel={(c) => c.name}
  aria-label="Customer"
  renderTrigger={([selected]) => (
    <RecordChip
      icon={<Building2 />}
      value={selected?.name}
      placeholder="No customer"
    />
  )}
/>

Long valuesCopy Anchor Link

The trigger is one line and cuts a long value off. For a long user-entered name — a product, a task, a customer — in a dialog, sheet or popover, pass wrap: the trigger's fixed height becomes a minimum (one line still measures the same) and the picked name runs onto as many lines as it needs, and a long option wraps in the list instead of running out of the panel. A long word with no spaces breaks anywhere. The wrapper writes data-wrap. The person contract's name and email stay on one line.

Rich rowsCopy Anchor Link

renderItem draws a row (it defaults to itemToStringLabel); renderValue draws the trigger face when it should differ. Neither is used for people — see People. Filtering always runs against itemToStringLabel, so include everything a user might type — an owner, a code, an alias.

Server searchCopy Anchor Link

remote hands filtering to the server: the list shows items as given and never filters them locally. onSearchChange reports the typed query, loading shows skeleton rows while there are none yet (two lines with itemToSecondaryLabel) and a small spinner while rows already shown stay, announcing "Searching…" through the panel's status region, error shows in the panel with a Try again button (onRetry, or loadMore.onLoadMore), and loadMore pages on scroll: a sentinel after the last option loads the next page as the reader scrolls or arrows toward it, with skeleton options while it loads — no button. useAsyncSearch returns exactly these props — spread its result. leadingItems are listed first and never filtered out ("Me", "Unassigned"). A value that is not in the current page still shows its label.

Several values and option detailsCopy Anchor Link

multiple makes value an array: rows toggle, the panel stays open while you pick, the trigger reads {a}, {b} or {n} selected (countLabel), each option reports aria-selected, and a form posts every key under name. itemToDescription adds a second line read as the option's description; itemToDisabledReason disables an option while keeping it reachable, with the reason as its description. groupBy puts the rows under headings, in first-seen order; groupOrder lists the headings that come first whatever the rows' order.

Add an optionCopy Anchor Link

onCreateOption(query) lets the reader add what they typed. While the search text matches no option's label exactly (ignoring case and the spaces around it), the list ends with an "Add “text”" row (createLabel), reached with the arrows and Enter like any option, and the empty message gives way to it. Choosing it calls onCreateOption with the trimmed text; the option the promise resolves with becomes the selection, or joins it with multiple. A rejected promise selects nothing, so report the failure from your handler.

DisabledCopy Anchor Link

PeopleCopy Anchor Link

People have one contract: itemToStringLabel (the name), itemToSecondaryLabel (the email) and itemToAvatar (the Person). With either of the last two, the component draws each option as one PersonOption — avatar, name, then a smaller muted email, each exactly once — and the trigger as the avatar plus the name. The local search matches the name and the email. The selected tick matches by itemToKey, so options from a server search (fresh objects on each fetch) tick exactly as static ones do.

This is the only correct usage — pass no renderItem or renderValue:

<SearchableSelect
  items={people}
  value={owner}
  onValueChange={setOwner}
  itemToKey={(p) => p.id}
  itemToStringLabel={(p) => p.name}
  itemToSecondaryLabel={(p) => p.email}
  itemToAvatar={(p) => p}
  searchLabel="Search people"
/>

Never return a PersonOption (or a PersonAvatar) from renderItem alongside the person contract: the rows would carry two avatars and two emails. The component prevents it — with the person contract, renderItem and renderValue are ignored and a development build logs one console.warn naming the ignored prop.

itemToAvatar returns the option's Person (name, image, hue): each row then leads with its PersonAvatar — the photo, else the initials on the person's hue — and so does a single selection on the trigger. ListFacet takes the same prop for a people filter.

Inactive memberCopy Anchor Link

itemToBadge puts a small muted outline badge right after a person's name — "Inactive" for someone who has left the workspace but still owns records you can filter by. List active people first. ListFacet takes the same prop; outside a picker (a DropdownMenuItem, a list of your own) use <PersonOption badge="Inactive" /> directly.

<ListFacet
  label="Recorded by"
  items={recorders}
  value={recorder}
  onValueChange={setRecorder}
  itemToKey={(p) => p.id}
  itemToStringLabel={(p) => p.name}
  itemToSecondaryLabel={(p) => p.email}
  itemToBadge={(p) => (p.active ? undefined : "Inactive")}
  searchLabel="Search people"
/>

API ReferenceCopy Anchor Link

className lands on the trigger; containerClassName on the wrapper. ref is the trigger button (the focusable host — the panel is portaled); rootRef is the wrapper, for a component whose own public ref is its root.

AccessibilityCopy Anchor Link

• The trigger is role="combobox" with aria-expanded and aria-haspopup="dialog" — Base UI's pattern for a Select-style combobox whose input lives inside the panel. role="combobox" prohibits name-from-content, so the trigger is always named: by its FieldLabel inside a Field, by a <label for> pointing at id, or by aria-label. With none of these it falls back to the selected item's label, then the placeholder — never over a label it has.
• Outside a Field, aria-invalid and aria-describedby wire the trigger to an error message.
• The search field is named by searchLabel (default "Search"; name what it searches, "Search people") and focused when the panel opens. Inside a Field, the Field's label names the trigger only — the search field keeps its own name.
• The clear control is a Button size="icon-xs" sibling of the trigger with its own aria-label, so the trigger never nests one interactive control inside another.
• Selection is one code path for pointer and keyboard alike: both go through the Combobox root's onValueChange.

Do / Don'tCopy Anchor Link