EntityPicker

Usage examples

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

const labels: ComboboxOption[] = [
  { value: 'bug', label: 'Bug' },
  { value: 'feature', label: 'Feature' },
  { value: 'docs', label: 'Documentation' },
  { value: 'perf', label: 'Performance' },
];

function LabelsDemo() {
  const [values, setValues] = useState(['bug', 'perf']);
  const [options, setOptions] = useState(labels);
  return (
    <Field style={{ width: '100%', maxWidth: 300 }}>
      <FieldLabel>Labels</FieldLabel>
      <EntityPicker
        multiple
        options={options}
        values={values}
        onValuesChange={setValues}
        placeholder="Add labels"
        onCreate={(q) => {
          const option = { value: q.toLowerCase(), label: q };
          setOptions((list) => [...list, option]);
          return option;
        }}
      />
    </Field>
  );
}

<LabelsDemo />

import { useState } from 'react';
import { Button, EntityPicker } from '@rookcom/monarch-react';
import type { ComboboxOption } from '@rookcom/monarch-react';

// BoardIcon, GridIcon, ListIcon: demo icons from the docs site; use your own.

const makeProjects = (): ComboboxOption[] => [
  {
    value: 'website',
    label: 'Website refresh',
    hint: 'WEB',
    group: 'Active',
    media: <BoardIcon />,
  },
  {
    value: 'mobile',
    label: 'Mobile onboarding',
    hint: 'MOB',
    group: 'Active',
    media: <ListIcon />,
  },
  {
    value: 'billing',
    label: 'Billing migration',
    hint: 'BIL',
    group: 'Active',
    media: <GridIcon />,
  },
  {
    value: 'research',
    label: 'Customer research',
    hint: 'RES',
    group: 'Paused',
    description: 'Paused until next quarter',
    media: <ListIcon />,
  },
];

function ChipDemo() {
  const [projects] = useState(makeProjects);
  const [value, setValue] = useState<string | null>('website');
  const current = projects.find((p) => p.value === value);
  return (
    <EntityPicker
      options={projects}
      value={value}
      onValueChange={setValue}
      size="sm"
      trigger={
        <Button
          size="xs"
          aria-label={`${current?.hint ?? 'None'}: project ${current?.label ?? 'none'}`}
        >
          {current?.hint ?? 'None'}
        </Button>
      }
    />
  );
}

<ChipDemo />

Purpose

The "click the field, search, pick a record" pattern most products end up rebuilding: a trigger (a field-style button or the product’s own chip) opens a popover with a search box and a listbox. The product injects the records, search, rendering and creation; EntityPicker owns the trigger, popover, keyboard and selection model.

Design principles

• No product data in Monarch: records arrive as options or from onSearch, and rich rows come from media, description, hint or renderOption.
• One picker for every record type, so keyboard behaviour and accessibility are the same everywhere.
• Prefix matches rank first (sortByMatch, on by default), so "in" finds India before Argentina.
• Single pick closes and returns focus to the trigger; multiple keeps the list open.

API reference

import { EntityPicker } from '@rookcom/monarch-react';

Forwards its ref to the trigger button. Native button attributes go to the default trigger.

The panel is a Radix Popover (role="dialog") containing an inline Combobox and an optional footer.

Shares option, message and search types with Combobox (ComboboxOption, ComboboxMessages, ComboboxSearchContext).

Generated from the TypeScript declarations of packages/react/src/components/forms/entity-picker.

Properties

trigger replaces the default trigger; it must accept a ref and name itself, with its visible text in the name (for example aria-label="WEB: project Website refresh").

footer may be a function of { close, query }, for actions such as "Create “query”" or "Manage projects".

Variants

States

Interaction behaviour

• Clicking the trigger (or Enter / Space on it) opens the popover and focuses the search box.
• Typing filters (or calls onSearch after the debounce); arrows move, Enter or a click picks.
• Single: picking closes the popover and returns focus to the trigger. Multiple: picking toggles and the list stays open.
• clearOption adds a first option such as "No project"; onCreate adds "Create “text”".
• Escape or clicking outside closes without changing the value.

Keyboard support

Accessibility

Role

select-only combobox (the trigger) opening a dialog that holds a search combobox and a listbox

Accessible name

The Field label or aria-label; the selected value is the trigger’s content.

• The default trigger follows the APG select-only combobox: role="combobox", named by its label, with aria-expanded, aria-haspopup="dialog" and aria-controls; its text is the value.
• The popover is a named dialog; focus moves into the search box and back to the trigger on close.
• The search box is an APG combobox with aria-activedescendant; groups are labelled role="group".
• With multiple the listbox is aria-multiselectable.

Responsive behaviour

• The popover is at least 16rem wide (or the trigger width) and never wider than the viewport minus 2rem.
• The trigger truncates long labels with an ellipsis; the list scrolls within 18rem.

Theme support

• Trigger, panel and options use semantic tokens shared with Input and the menu styles; light, dark and more-contrast themes apply.
• The popover entrance animation respects reduced motion.

Do and don't

Related components

• Combobox: The search and list it is built on; use directly for an input-style field.
• AssigneePicker: People preset with avatars.
• Select: Short lists without search.
• Popover: The floating panel.

Dependencies

The trigger uses .mn-input; the panel uses .mn-menu.

Testing coverage

• Opens from a labelled trigger, focuses the search, picks with Enter, closes and refocuses the trigger.
• Groups and prefix ranking; Escape closes without a change.
• Multiple stays open, toggles and summarises as "first +N".
• Clear option, footer with close and query, custom trigger.
• Async search plus create keeps the picked label; disabled and invalid from Field.

Tests: packages/react/src/components/forms/entity-picker