Entity Picker
Pick one or several records (people, roles, groups) from a fixed list or a server search, with labels that survive the search.
Search by name. The description helps tell similar roles apart.
Usage
import { EntityPicker, type EntityOption } from "@zynactra/ui/entity-picker"<EntityPicker id="role" options={roles} value={roleId} onValueChange={setRoleId} />Each option is { value, label, description? }. value is the stable ID you store; label is what people read; description tells similar options apart. onValueChange also gets the chosen option, so you never look the label up again.
Examples
Server search, several values
Pass loadOptions(query, signal) instead of options. It is called after debounceMs (250 by default) and aborted when the query changes. Pass the options already in the value as selectedOptions so their labels show before any search returns them.
Searches as you type. Already chosen people keep their names.
Creatable
With creatable, what was typed is offered as a new value when nothing matches. Use it for free-form identifiers that may not exist yet, such as identity provider group names.
Pick a group seen before, or type one that hasn't signed in yet.
Guidelines
- Use it when the list is long, comes from the server, or its items need a second line. For a handful of fixed words, use Select or Radio Group.
- Store the
value, show thelabel. Never make people type an ID. - Label it with a Field (
FieldLabel htmlForthe picker'sid), and put errors inFieldError. loadOptionsmust honour the abort signal, or old answers can arrive after new ones.
API reference
Built on Combobox, which takes its behaviour from Base UI. See the Base UI Combobox docs.