Object picker

Problem Context

• The product stores a stable object identity, not only the label the user typed.
• Different entities may share the same name or have similar labels.
• Users may need to see object type, owner, status, location, email, avatar, account, project, or permission scope before selecting.
• Search results may come from a remote service, directory, graph, CRM, repository, or data table with access controls.
• The selected object may affect assignment, permissions, ownership, billing, workflow routing, or linked records.

Selection Rules

• Choose object picker when users must select an existing record, person, group, file, account, project, team, workspace, or other entity with a stable ID.
• Use combobox when the main requirement is one popup-owned field value and entity identity metadata is not central to the task.
• Use autocomplete when suggestions complete a known text value and the submitted value does not require previewing an object record.
• Use multi-select or chip selection when users choose several simple values; use object picker for one or more entities only when each selected item needs identity, metadata, or permission-aware validation.
• Use transfer list when users move objects into a separate selected destination set with ordering, locked items, or batch review.
• Use tree selection when hierarchy is the primary way to understand and select entities.
• Restrict result scope to the current task when possible, and label any broadened scope such as All records, Archived, External, or Directory.
• Require a selected object ID before submit when free text is not valid.
• Clear the selected ID or mark it unresolved whenever the visible text no longer matches the committed object.

Required States

• Empty object lookup field with label, helper text, and current search scope.
• Focused field with popup available and no committed object.
• Loading remote results state for the current query and scope.
• Filtered result list with active result and disambiguating metadata.
• Duplicate-label result state with distinct type, status, owner, region, email, or ID.
• Selected object state with visible chip, preview card, object type, and stable identity.
• Edited-after-selection unresolved state where the submitted ID is cleared.
• No results in current scope state with a safe way to broaden or change scope.
• Permission-restricted result state that explains why an object is unavailable when the product can disclose it.
• Required valid-object validation state for unresolved text or empty selection.
• Disabled or read-only state with selected object still inspectable.

Interaction Contract

• Typing searches or filters permitted objects without committing the first visible result.
• Arrow keys or equivalent controls move the active result independently from the selected object.
• Enter, pointer selection, or an explicit Choose action commits the active object and synchronizes the selected ID, visible label, and preview.
• Editing the visible text after a committed selection clears or invalidates the selected object until another result is chosen.
• Scope changes refresh results while preserving the selected object only if it still belongs to the allowed scope.
• The user can clear the selected object and recover from no-result, loading, unavailable, and validation states without losing form context.

Implementation Checklist

• Define the object type, submitted ID, display label, secondary fields, permission scope, and duplicate-label strategy before building the picker.
• Use an accessible combobox, listbox, dialog, or platform picker structure with labelled input, expanded state, active option, selected state, and validation text.
• Show secondary metadata such as email, owner, status, type, region, path, account, project, or ID in every result row where labels may collide.
• Synchronize visible text, selected object, submitted ID, preview card, clear action, and validation state as one state machine.
• Debounce remote search, cancel stale responses, expose loading and no-result states, and avoid leaking inaccessible object names.
• Test duplicate names, archived or inactive records, permission-denied objects, slow search, scope changes, stale IDs, keyboard selection, screen readers, high zoom, mobile fallback, and localization.

Common Generated-UI Mistakes

• Treating the picker as a free text field when the system requires an existing object ID.
• Displaying only names for entities that commonly share names.
• Submitting a hidden object ID after the visible text changes.
• Searching an unbounded directory when the task has a clear project, account, group, or status scope.
• Using object picker for a short static enum that should be radio, select, listbox, or checkbox group.
• Hiding unavailable or archived status until after the user saves.

Critique Questions

• What exact object ID is submitted, and can the user inspect it before saving?
• Can users distinguish same-named entities without opening another page?
• Does editing the visible label clear the committed object identity?
• Is search limited to the task's relevant scope, and are broadened scopes labelled?
• What happens when results are loading, empty, stale, archived, inaccessible, or duplicated?