# Lwc Record Picker

> Guides using the lightning-record-picker base component for single-record selection in LWC, covering display-info, matching-info, graph-QL filters, and accessibility.

- Skill: `pranavnagrecha/lwc-record-picker` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds add pranavnagrecha/lwc-record-picker`
- Raw SKILL.md: https://api.skillmd.com/api/skills/pranavnagrecha/lwc-record-picker/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend, Frontend Frameworks
- Tags: Lightning Record Picker, Lookup, Lwc, Record Picker, Salesforce
- Author: PranavNagrecha (https://skillmd.com/u/pranavnagrecha)
- Updated: 2026-08-22
- Page: https://skillmd.com/skills/pranavnagrecha/lwc-record-picker

---


# 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

1. Confirm object is supported (standard + most custom). External objects unsupported.
2. Define `display-info` and `matching-info` — always set primaryField.
3. Build `filter` with graph-QL criteria for scope.
4. Wire `onchange` to capture selected Id and fetch additional record details.
5. Add accessibility attributes: label is required; leverage built-in keyboard nav.
6. Write jest test asserting `change` event dispatch.
7. 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

1. **External Objects not supported.** The picker targets standard/custom only.
2. **Person Account nuance** — when Person Accounts are on, `Account` results include persons; filter if you want companies only.
3. **`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 |

## Related Skills

- `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