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 multi-select custom pickers (use lwc-multi-select-lookup). NOT for external-object lookup (use lwc-external-lookup).
Best use case
lwc-record-picker is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
lightning-record-picker base component (Winter '24 GA): object/record filter, displayInfo/matchingInfo, graph-ql filters, accessibility. Replaces ad-hoc lookup inputs. NOT for multi-select custom pickers (use lwc-multi-select-lookup). NOT for external-object lookup (use lwc-external-lookup).
Teams using lwc-record-picker should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/lwc-record-picker/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How lwc-record-picker Compares
| Feature / Agent | lwc-record-picker | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
lightning-record-picker base component (Winter '24 GA): object/record filter, displayInfo/matchingInfo, graph-ql filters, accessibility. Replaces ad-hoc lookup inputs. NOT for multi-select custom pickers (use lwc-multi-select-lookup). NOT for external-object lookup (use lwc-external-lookup).
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# 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 designRelated Skills
record-access-troubleshooting
Diagnose why a user can or cannot see/edit a record: UserRecordAccess SOQL, Why Can a User Access This Record debug log, OWD, role hierarchy, sharing rules, manual/team/apex shares, implicit parent share. NOT for field-level security (use field-level-security-audit). NOT for designing sharing (use sharing-selection decision tree).
lwc-lightning-record-forms
Lightning Data Service form components for LWC — when to use lightning-record-form vs lightning-record-edit-form vs lightning-record-view-form, output-field vs input-field, density modes, layout types (Compact/Full), and the platform-managed validation/save/error UI. NOT for fully custom form layouts (use lwc/lwc-custom-form-with-uiRecordApi) or aura:recordEditForm (Aura is deprecated for new work).
record-triggered-flow-patterns
Use when designing or reviewing Salesforce record-triggered Flows, especially before-save vs after-save behavior, entry criteria, recursion avoidance, and when to escalate to Apex. Triggers: 'before save vs after save', '$Record__Prior', 'record-triggered flow', 'order of execution', 'flow recursion'. NOT for screen-flow UX or pure bulkification work when the trigger model is already correct.
flow-record-save-order-interaction
Reason about how record-triggered flows interleave with the Salesforce Save Order (validation, before-save flows, before triggers, duplicate rules, after-save flows, workflow, after triggers, assignment, auto-response, escalation). Trigger keywords: save order, before-save flow, after-save flow, dml order, trigger vs flow order. Does NOT cover writing trigger handlers, approval process setup, or workflow rule migration.
flow-record-locking-and-contention
Diagnose and prevent UNABLE_TO_LOCK_ROW + parent-record contention in record-triggered, scheduled, and screen flows by mapping the implicit lock chain and applying decouple patterns (Platform Events, Queueable handoff, Scheduled Paths). NOT for general flow bulkification — see flow-bulkification. NOT for fault-path catch logic — see flow-rollback-patterns.
flow-get-records-optimization
Optimize Get Records elements in Flow: filter sharpness, field selection, sort-and-limit placement, caching via formula resources, and avoiding repeated queries in loops. Trigger keywords: get records, flow soql, flow query limit, flow performance, record lookup. Does NOT cover Apex SOQL, Data Cloud queries, or external object lookups.
record-merge-implications
Use when merging Account, Contact, or Lead records in Salesforce and needing to understand what data is kept, what is deleted, and what side effects occur on related records. Triggers: 'which fields win in a merge', 'child records after merge', 'merge duplicate accounts', 'what happens to opportunities after contact merge', 'Lead merge field resolution'. NOT for deduplication strategy design (use data-quality-and-deduplication), NOT for Apex Merge DML beyond its direct implications.
architecture-decision-records
Author and maintain Architecture Decision Records (ADRs) for Salesforce implementations: capture chosen approach, rejected alternatives, constraints, and consequences. Trigger keywords: adr, architecture decision record, design decision log, technical decision. Does NOT cover project roadmap planning, release notes, or RFC workflow for features.
record-locking-and-contention
Use when diagnosing or preventing UNABLE_TO_LOCK_ROW errors, record lock contention in Apex or Bulk API loads, FOR UPDATE locking, parent-child lock escalation, and deadlock scenarios. Triggers: 'UNABLE_TO_LOCK_ROW', 'record lock contention', 'FOR UPDATE SOQL', 'deadlock', 'lock timeout'. NOT for approval-process record locking (admin/approval-processes) or optimistic concurrency via timestamps.
apex-record-clone-patterns
SObject.clone(preserveId, isDeepClone, preserveReadonly, preserveAutonumber): shallow vs deep clone semantics, related-record replication, clone with parent repointing, autonumber preservation. NOT for data migration (use bulk-api-and-large-data-loads). NOT for record snapshots (use field-history-tracking).
record-types-and-page-layouts
Use when designing, auditing, or simplifying Record Types and Page Layouts. Triggers: 'record type', 'page layout', 'different picklist values', 'different fields per team', 'dynamic forms'. NOT for sharing rules or FLS — record types don't control data access.
record-type-strategy-at-scale
Use when designing or refactoring record types across objects with many profiles, business processes, or picklist variations. Covers layout assignment explosion, Dynamic Forms migration, and record type ID portability. NOT for basic record type setup or page layout assignment — see record-types-and-page-layouts for introductory guidance.