SearchCombobox

Use SearchCombobox when the reader has to search a known list to choose one item: a scheme, a category, a role. The button shows the choice; the menu opens with a search field on top and a list that filters while typing. For a short fixed list where searching does not help, use Select; when the server has to search, use AsyncCombobox.

// apps/docs/examples/ui/search-combobox.tsx'use client';
import {useState} from 'react';
import {SearchCombobox} from '@workspace/active-ui/components/composed/search-combobox';import {  Field,  FieldDescription,  FieldLabel,} from '@workspace/active-ui/components/primitives/field';
// A local list: the component filters it. `keywords` is searched, not shown.const SCHEMES = [  {value: 'dc-2024', label: 'Defined contribution 2024', keywords: 'DC'},  {value: 'db-final', label: 'Final salary', keywords: 'DB'},  {value: 'db-average', label: 'Career average', keywords: 'DB CA'},  {value: 'dc-2019', label: 'Defined contribution 2019', keywords: 'DC'},  {value: 'anw', label: 'Surviving dependants', keywords: 'ANW gap'},  {value: 'closed', label: 'Early retirement (closed)', disabled: true},];
/** * A searchable choice from a local list. Type on the focused button to * start searching; the search ignores case and accents and also matches the * hidden codes (try "DB"). The value is the option's `value`, never its label. */export default function SearchComboboxExample() {  const [scheme, setScheme] = useState<string | null>('db-average');  return (    <Field className="w-full max-w-xs">      <FieldLabel htmlFor="scheme">Pension scheme</FieldLabel>      <SearchCombobox        id="scheme"        options={SCHEMES}        value={scheme}        onValueChange={setScheme}        placeholder="Choose a scheme"        searchLabel="Search schemes"        searchPlaceholder="Search…"        emptyText="No scheme found."        locale="en"        aria-describedby="scheme-value"      />      <FieldDescription id="scheme-value">        Value: <code>{scheme ?? 'null'}</code>      </FieldDescription>    </Field>  );}

What the composition adds#

SearchCombobox is the Combobox primitive with a button as trigger and the search field inside the menu. It adds:

• identity by value: two options with the same label stay distinct, and changing the language does not change the stored value;

• filtering per language: case- and accent-insensitive, anywhere in the label, with the collator of the locale you pass. Under es, Espana does not find España; under en it does;

• keywords: extra text that is searched but not shown, such as a code;

• typing on the button starts a search: a key typed on the focused, closed button opens the menu and becomes the start of the query, instead of choosing the first matching option;

• readOnly shows the choice but does not open; required marks the button for assistive technology.

No groups, no clear button, no multiple choice (SearchMultiCombobox), no result limit or virtualisation, and no loading state.

Usage#

import {SearchCombobox} from '@workspace/active-ui/components/composed/search-combobox';
<SearchCombobox  id="scheme"  options={[{value: 'db-final', label: 'Final salary', keywords: 'DB'}]}  value={scheme} // the option's value, or null  onValueChange={setScheme}  placeholder="Choose a scheme"  searchLabel="Search schemes"  searchPlaceholder="Search…"  emptyText="No scheme found."  locale="en"/>;

What your application provides#

• The complete list, with stable values and translated labels; the component filters it, so do not filter it as well.

• The reader's language as locale, every text translated, and the form binding.

• What null means for the field, and the validation.

Accessibility and keyboard#

• The button is the field: name it with FieldLabel htmlFor its id; aria-describedby and aria-invalid go to the button.

• Enter, Space or ArrowDown open the menu; the search field is named by searchLabel.

• In the menu, ArrowUp and ArrowDown move through the hits, Enter chooses, Escape closes and returns focus to the button.

API#

interface SearchComboboxOption {
  value: string;
  label: string;
  disabled?: boolean;
  keywords?: string;
}

interface SearchComboboxProps extends Omit<
  React.ComponentProps<'button'>,
  'value' | 'defaultValue' | 'onChange' | 'children'
> {
  options: readonly SearchComboboxOption[];
  value: string | null;
  onValueChange: (value: string | null) => void;
  placeholder: string;
  searchLabel: string;
  searchPlaceholder: string;
  emptyText: string;
  locale: LocaleCode;
  readOnly?: boolean;
  required?: boolean;
}