| UI or UX | UI + UX - Existing-entity lookup and selected-object confirmation | UI + UX - Single-value input widget with owned popup | UI + UX - Input widget with suggestion behavior | UI + UX - Multi-value picker widget |
| UI guidance | Render a labelled lookup field with search text, scoped result list, active result, selected object chip or preview, object type, stable ID or equivalent key, secondary metadata, clear action, no-result state, loading state, and validation text. | Render a persistent label, editable or select-only value surface, popup indicator, collapsed and expanded states, option popup, active option, committed selection, clear action when supported, help text, and error text. | Render a labeled text field, suggestion popup, highlighted option, selected value, and no-match state. | Render a filter input, open option list, selected-value chips, remove controls, checked option states, clear-all control, and validation state. |
| UX guidance | Use an object picker when the user must choose an existing entity whose identity matters beyond the displayed label, such as a record, person, group, account, file, team, project, or workspace. | Use a combobox when users need one value from a large or dynamic option set and benefit from opening a popup, typing to narrow it, or copying/editing the displayed value. | Help users complete a known value faster without forcing an incorrect suggestion. | Help users choose multiple values from a large, compact, or dynamic option set. |
| Good UI | A Related account field shows two Acme Retail records with account ID, region, status, and owner, then displays a selected-object preview card before saving. | An Assignee combobox shows a label, typed text, disclosure button, active option in a listbox, selected-value status, and an error when typed text has no accepted option. | Persistent label above the input, readable text size, clear popup alignment, and visible highlighted option. | Selected values are shown as removable chips or checked rows with clear labels. |
| Bad UI | A text field accepts Acme Retail as free text even though the backend needs a record ID. | A custom dropdown displays matching labels but never exposes expanded state, active option, or the controlled popup. | Placeholder-only label that disappears after typing. | Selected values hidden inside a closed dropdown. |
| Good UX | A user searches Acme, compares two same-named records by region and status, selects the active EMEA account, and reviews the selected account ID before saving. | A user types Ada, moves the active option with Arrow Down, presses Enter to accept Ada Lovelace, then edits the label and sees the selected ID clear until a new option is accepted. | Typing filters suggestions while preserving the exact typed value. | Users can search, add, remove, review, and submit multiple values without losing context. |
| Bad UX | A user types a person name and presses Save, but no actual user account was selected. | The component automatically commits the first match as soon as a user types one character. | Automatically forcing the first suggestion into the field. | Removing a value is impossible by keyboard. |
| Best fit | Users assign, link, reference, invite, route, or attach an existing entity. | Users choose one value from a large, dynamic, or filterable option set. | The list is long but values are known. | Users choose many values from a long predefined list. |
| Avoid when | Any arbitrary text is valid. | The list is short enough for native select, radio buttons, or segmented controls. | The task is open-ended query exploration. | The set is short and independent choices should stay visible. |
| Required state | Empty object lookup field with label, helper text, and current search scope. | Collapsed empty state with label, help text, and popup affordance. | Empty input state. | No selected values state with empty selected set. |
| Accessibility burden | Give the lookup field a persistent label and helper text that explains the expected object type. | Expose the value surface with role combobox or a native control that maps correctly to combobox semantics. | Expose combobox expanded state, active descendant, and option labels. | Expose selected state for options and labels for remove controls. |
| Common misuse | Treating the picker as a free text field when the system requires an existing object ID. | Using a custom combobox for a short list where native select, radio buttons, or segmented controls would be simpler. | Forcing the first suggestion when the user did not choose it. | Hiding selected values inside a closed menu. |