Combobox

Usage examples

import { useState } from 'react';
import { Combobox, Field, FieldLabel } from '@rookcom/monarch-react';
import type { ComboboxOption } from '@rookcom/monarch-react';

const reviewers: ComboboxOption[] = [
  { value: 'u1', label: 'Priya Raman', hint: 'Design', group: 'In this team' },
  { value: 'u2', label: 'Jonas Weber', hint: 'Platform', group: 'In this team' },
  { value: 'u3', label: 'Amara Okafor', group: 'Everyone else' },
  { value: 'u4', label: 'Lucas Martin', group: 'Everyone else' },
  { value: 'u5', label: 'Mei Chen', group: 'Everyone else' },
];

function ReviewersPicker() {
  const [values, setValues] = useState(['u1', 'u3']);
  return (
    <Field style={{ width: '100%', maxWidth: 340 }}>
      <FieldLabel>Reviewers</FieldLabel>
      <Combobox
        multiple
        options={reviewers}
        values={values}
        onValuesChange={setValues}
        sortByMatch
        placeholder="Add a reviewer"
      />
    </Field>
  );
}

<ReviewersPicker />

import { useState } from 'react';
import { Combobox, Field, FieldDescription, FieldLabel } from '@rookcom/monarch-react';
import type { ComboboxOption } from '@rookcom/monarch-react';

const CITIES = ['Lisbon', 'London', 'Lyon', 'Lagos', 'Lima', 'Leeds', 'Lucknow', 'Ljubljana'];

/** A pretend server: answers after a short delay and honours the abort signal. */
function searchCities(query: string, { signal }: { signal: AbortSignal }) {
  return new Promise<ComboboxOption[]>((resolve, reject) => {
    const timer = setTimeout(() => {
      const q = query.toLowerCase();
      resolve(
        CITIES.filter((c) => c.toLowerCase().includes(q)).map((c) => ({ value: c, label: c })),
      );
    }, 300);
    signal.addEventListener('abort', () => {
      clearTimeout(timer);
      reject(new DOMException('Aborted', 'AbortError'));
    });
  });
}

function CityPicker() {
  const [value, setValue] = useState<string | null>(null);
  const [created, setCreated] = useState<ComboboxOption[]>([]);
  return (
    <Field style={{ width: '100%', maxWidth: 300 }}>
      <FieldLabel>City</FieldLabel>
      <Combobox
        onSearch={searchCities}
        value={value}
        onValueChange={setValue}
        valueOptions={created}
        onCreate={(q) => {
          const option = { value: q, label: q };
          setCreated((list) => [...list, option]);
          return option;
        }}
        messages={{ create: (q) => `Use “${q}”` }}
        clearOption={{ label: 'No city' }}
        placeholder="Start typing"
      />
      <FieldDescription>
        Results come from a server; typing aborts the last request.
      </FieldDescription>
    </Field>
  );
}

<CityPicker />

import { Combobox } from '@rookcom/monarch-react';
import type { ComboboxOption } from '@rookcom/monarch-react';

const reviewers: ComboboxOption[] = [
  { value: 'u1', label: 'Priya Raman', hint: 'Design', group: 'In this team' },
  { value: 'u2', label: 'Jonas Weber', hint: 'Platform', group: 'In this team' },
  { value: 'u3', label: 'Amara Okafor', group: 'Everyone else' },
  { value: 'u4', label: 'Lucas Martin', group: 'Everyone else' },
  { value: 'u5', label: 'Mei Chen', group: 'Everyone else' },
];

<div
  style={{
    width: '100%',
    maxWidth: 300,
    border: '1px solid var(--mn-color-border-subtle)',
    borderRadius: 'var(--mn-radius-lg)',
  }}
>
  <Combobox
    inline
    aria-label="Search people"
    listLabel="People"
    options={reviewers}
    defaultValue="u2"
    placeholder="Search…"
  />
</div>

Purpose

A select people type into: the input is the combobox and the options are a listbox. It covers long static lists, server search with debounce and abort, several values as chips, and the inline list that EntityPicker and TimezoneSelect build on.

Design principles

• The input keeps focus; options follow the aria-activedescendant pattern (WAI-ARIA APG combobox).
• In single mode the input always reflects the selection: unmatched text is reverted on blur and Escape.
• The product owns data and rules: search, creation and option content come in through props.
• Late server answers never overwrite newer ones: a new query aborts the last request.

API reference

import { Combobox, matchComboboxOption } from '@rookcom/monarch-react';

Forwards its ref to the <input>. Native input attributes pass through, except value, defaultValue, onChange, size and type.

matchComboboxOption(option, query) is the default filter, exported for products that extend it.

Single mode uses value / defaultValue / onValueChange; multiple uses values / defaultValues / onValuesChange.

Generated from the TypeScript declarations of packages/react/src/components/forms/combobox.

Properties

onSearch(query, { signal }) returns a promise of options. Pass the signal to fetch so superseded requests are cancelled.

onCreate(query) may return the new option (or a promise of it) to select it.

Variants

States

Interaction behaviour

• Typing opens the list and filters it (label, hint and keywords; sortByMatch ranks prefix matches first).
• Clicking an option selects it. Single mode closes the list; multiple toggles the value and keeps it open.
• With onSearch, opening searches the empty query at once; typing searches after searchDebounce ms (default 250).
• With onCreate, a "Create “text”" option appears when no label matches the text exactly.
• clearOption adds a first option that clears the selection.
• limit renders only the first matches and says how many are hidden.
• Chip remove buttons and Backspace remove values; each change is announced in a polite status region.
• The chevron button toggles the list and returns focus to the input.

Keyboard support

Accessibility

Role

combobox, controlling a listbox

Accessible name

A FieldLabel in the surrounding Field, or aria-label. The listbox is named by listLabel, the Field label or aria-label.

• aria-autocomplete="list", aria-expanded, aria-controls and aria-activedescendant are set on the input.
• Grouped options sit in role="group" elements labelled by their heading.
• With multiple the listbox is aria-multiselectable; chips are a list with named remove buttons.
• Loading, empty, error and "showing N of M" messages are role="status".
• Option media is decorative (aria-hidden); the label names the option.

Responsive behaviour

• The popover list matches the input width (at least 12rem) and limits its height to the space available.
• In multiple mode chips wrap onto new lines and the control grows; the text input keeps at least 5rem.
• Long labels wrap; hints truncate with an ellipsis at 40% of the row.

Theme support

• Input, chip and menu colours are semantic tokens shared with Input, TagInput and DropdownMenu, so light, dark and more-contrast themes apply.
• The menu entrance animation comes from the foundation and respects reduced motion.

Do and don't

Related components

• Select: Short lists without search.
• EntityPicker: Button-triggered record picker built on the inline Combobox.
• TagInput: Free-form values as chips.
• Field: Label and error wiring.

Dependencies

Uses .mn-input from text-field and .mn-menu from the shared menu styles.

Testing coverage

• Filters, navigates with the keyboard (aria-activedescendant) and selects with Enter; Escape restores the selection.
• Grouped options in labelled groups; hint and keyword matching; prefix ranking; custom rendering; limit message; clear option.
• PageDown/PageUp, Home/End, Alt+ArrowDown/Up; Backspace clears.
• Multiple: toggles, stays open, chips with remove buttons, Backspace removes, announcements, disabled chips.
• Async: debounce, abort of superseded queries, late answers ignored, error with retry (button and Enter), minSearchLength, valueOptions labels.
• Create option selects what onCreate returns; hidden on an exact match. Inline mode.

Tests: packages/react/src/components/forms/combobox