Home / lwc / lwc-record-picker

lwc-record-picker

lightning-record-picker base component (Winter '24 GA): object/record filter, displayInfo/matchingInfo, graph-ql filters, accessibility. Replaces ad-hoc lookup inputs. NOT for a fully custom typeahead lookup — use lwc/lwc-custom-lookup.

v1.1.0
Salesforce Spring '25+
Updated 2026-05-19
User Experience
Operational Excellence

lwc
record-picker
lookup
lightning-base-components
accessibility

Open the skill folder on GitHub

LWC Record Picker

Activate when an LWC needs a user to search and select a single Salesforce record. lightning-record-picker (GA Winter '24) is the official base component; it replaces custom combobox+search implementations and hand-rolled lightning-lookup equivalents with one declarative tag.

Before Starting

Use lightning-record-picker rather than rolling a custom lookup.
Configure display-info and matching-info — they drive what the user sees and what fields search hits.
Set a filter for scoped choice lists (e.g., only active accounts).

Core Concepts

Minimum markup

<lightning-record-picker
    label="Account"
    placeholder="Search Accounts"
    object-api-name="Account"
    onchange={handleChange}>
</lightning-record-picker>

event.detail.recordId on change carries the selected record Id.

display-info / matching-info

<lightning-record-picker
    object-api-name="Contact"
    display-info={displayInfo}
    matching-info={matchingInfo}>
</lightning-record-picker>

displayInfo = {
    primaryField: 'Name',
    additionalFields: ['Account.Name', 'Email']
};
matchingInfo = {
    primaryField: { fieldPath: 'Name' },
    additionalFields: [{ fieldPath: 'Email' }]
};

Filter (graph-QL)

filter = {
    criteria: [
        { fieldPath: 'IsActive', operator: 'eq', value: true }
    ]
};

Limits search results.

Preselection

Set value={preselectedRecordId}. The picker fetches display fields and shows the chip.

Common Patterns

Pattern: Filtered contact picker scoped to account

Filter on AccountId = :this.accountId; filter updates when the account context changes.

Pattern: Multi-object picker via toggle

Two <lightning-record-picker> elements toggled by a dropdown that selects the object API name.

Pattern: Reset on context change

Programmatically set value = null (or re-query) when context changes.

Decision Guidance

Need	Component
Standard single-record lookup	lightning-record-picker
Multi-record select	lightning-record-picker (not supported) → build custom
External object	lightning-record-picker does not support; custom
Enforce record-type filter	Use `filter` criteria on RecordTypeId
Filter by complex formula	Server-side Apex + custom combobox

Recommended Workflow

Confirm object is supported (standard + most custom). External objects unsupported.
Define display-info and matching-info — always set primaryField.
Build filter with graph-QL criteria for scope.
Wire onchange to capture selected Id and fetch additional record details.
Add accessibility attributes: label is required; leverage built-in keyboard nav.
Write jest test asserting change event dispatch.
Migrate any legacy custom lookup components to this one.

Review Checklist

[ ] lightning-record-picker used instead of custom combobox
[ ] object-api-name supported by the base component
[ ] display-info primaryField set
[ ] matching-info matches display
[ ] filter scopes results to valid options
[ ] onchange handler captures recordId
[ ] Label is descriptive and required attribute set where mandatory
[ ] Jest test covers change event

Salesforce-Specific Gotchas

External Objects not supported. The picker targets standard/custom only.
Person Account nuance — when Person Accounts are on, Account results include persons; filter if you want companies only.
matching-info is required for custom search fields — without it, only primary field matches.

Output Artifacts

Artifact	Description
Picker config template	displayInfo / matchingInfo / filter examples
Migration plan	Legacy custom lookup → record-picker
Jest test helper	Mock event dispatch

lwc/lwc-forms-patterns — picker embedded in forms
lwc/lwc-lookup-custom-patterns — when base picker is insufficient
admin/custom-field-creation — lookup field design