| 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 | Show enough fields to distinguish same-named objects before selection, and keep the selected object preview visible after the popup closes so the submitted entity can be inspected. | 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. | Expose clear visual states for expanded, focused, highlighted, and selected options. | 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. | Preserve typed input and make selection reversible before submission. | 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. | A Department field opens a list of matching departments, keeps focus in the field while the active option moves, and clearly marks the committed department. | 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 visible assignee name changes after typing while an old hidden user ID remains selected for form submission. | 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. | Selection limits and duplicates are handled before submit. |
| Bad UX | A user picks the first Acme result because every row looks identical, then links the case to the wrong account. | 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. | Open filtered option list state. |
| 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. | Using autocomplete where users expect broad search results. | Hiding selected values inside a closed menu. |