LWC Custom Lookup
The standard lightning-input-field (inside an LDS form) or
lightning-record-picker (Spring '24+, free-standing) is the
correct choice for ~90% of lookup use cases. Reach for a custom
lookup only when those don't fit:
- Cross-org / external search — picking from a system other
than Salesforce (the Salesforce-side lookup needs a custom Apex
method that talks to the external).
- Computed filters that change per-row — filter set depends
on other field values that the running user just changed; the
declarative lookup filter cannot model.
- Multi-object search — one input that matches Accounts and
Contacts and Opportunities together (SOSL territory).
- Custom result rendering — second line, badges, conditional
icons; the standard picker shows one line.
The hard parts of a hand-rolled lookup are not the SOQL: they are
debounce, keyboard accessibility, the open/close state machine,
the pill UI, and not making the user search for the same thing
they already selected. Skip any of those and the component feels
broken even when it works.
Recommended Workflow
- Confirm
lightning-record-picker is not enough. Spring '24
added the standalone picker with display-info, matching-info,
and filter. It supports cross-object search via the
objectApiName array. Read its docs first.
- Design the Apex search. Use SOSL for multi-object,
short-string queries (
FIND :term IN ALL FIELDS RETURNING ...).
Use SOQL with LIKE only for single-object, indexed-field
matches. Both with WITH USER_MODE and
@AuraEnabled(cacheable=true). WITH USER_MODE is GA from API
57.0; the clause it replaces, WITH SECURITY_ENFORCED, no
longer compiles at 67.0+ (Summer '26).
- Debounce the search by 250-300ms. Use
setTimeout /
clearTimeout in the input's oninput handler. Without
debounce, every keystroke fires a callout — exhausting Apex CPU
and pinning the org.
- Build the open/close state machine. Three states: closed,
open-with-search-loading, open-with-results. Open on focus,
close on blur (with a 200ms delay so result clicks land
first), close on escape, close on selection.
- Implement keyboard navigation. Arrow up/down move
activeIndex, Enter selects, Escape closes. Render
aria-activedescendant on the input pointing at the result li
so screen readers track focus.
- Render the selected state as a pill. Once chosen, swap the
input for an SLDS pill (
<lightning-pill>) with a remove
action. Re-clicking the remove returns to search mode.
- Cache the SObject icon.
getObjectInfo gives the icon URL;
prepend it to results once per render rather than per result.
What This Skill Does Not Cover
- Lookups inside
lightning-record-edit-form — use
lightning-input-field and configure lookup filters in metadata.
lightning-record-picker (standalone, Spring '24+) — see
lwc/lwc-record-picker.
- Lookup filters at the field-metadata level — see
admin/lookup-filter-design.
- Type-ahead against external systems — see
integration/external-search-via-named-credential.
1---2name: lwc-custom-lookup3description: "Custom lookup component in LWC — typeahead/autocomplete that searches records via Apex SOSL/SOQL, shows pills, supports keyboard navigation, and manages open/close state. Use when lightning-input-field or lightning-record-picker won't work (cross-org search, computed filters, custom result rendering). NOT for the base lightning-record-picker — use lwc/lwc-record-picker. NOT for in-form lookups inside lightning-record-edit-form."4category: lwc5salesforce-version: "Spring '25+"6well-architected-pillars:7 - Performance8 - Security9triggers:10 - "lwc custom typeahead lookup component"11 - "lightning-record-picker not flexible enough"12 - "lwc autocomplete record search apex"13 - "search records lwc soql lookup pill"14 - "lwc lookup keyboard navigation arrow keys"15 - "debounce lookup search lwc apex callout"16 - "lookup with multiple object types lwc"17tags:18 - lookup19 - typeahead20 - search21 - sosl22 - keyboard-accessibility23inputs:24 - "Object(s) to search and which fields to show in results"25 - "Debounce window (ms) for search-as-you-type"26 - "Whether selection is single or multi-select"27outputs:28 - "LWC component template + JS controller with debounced search"29 - "Cacheable Apex method using SOSL or SOQL with WITH USER_MODE"30 - "Pill/chip rendering pattern for selected record(s)"31dependencies: []32version: 1.0.033author: Pranav Nagrecha34updated: 2026-05-0535metadata:36 source: https://skillmd.com/skills/pranavnagrecha/lwc-custom-lookup37---3839# LWC Custom Lookup4041The standard `lightning-input-field` (inside an LDS form) or42`lightning-record-picker` (Spring '24+, free-standing) is the43correct choice for ~90% of lookup use cases. Reach for a custom44lookup only when those don't fit:4546- **Cross-org / external search** — picking from a system other47 than Salesforce (the Salesforce-side lookup needs a custom Apex48 method that talks to the external).49- **Computed filters that change per-row** — filter set depends50 on other field values that the running user just changed; the51 declarative lookup filter cannot model.52- **Multi-object search** — one input that matches Accounts and53 Contacts and Opportunities together (SOSL territory).54- **Custom result rendering** — second line, badges, conditional55 icons; the standard picker shows one line.5657The hard parts of a hand-rolled lookup are not the SOQL: they are58debounce, keyboard accessibility, the open/close state machine,59the pill UI, and not making the user search for the same thing60they already selected. Skip any of those and the component feels61broken even when it works.6263## Recommended Workflow64651. **Confirm `lightning-record-picker` is not enough.** Spring '2466 added the standalone picker with `display-info`, `matching-info`,67 and `filter`. It supports cross-object search via the68 `objectApiName` array. Read its docs first.692. **Design the Apex search.** Use SOSL for multi-object,70 short-string queries (`FIND :term IN ALL FIELDS RETURNING ...`).71 Use SOQL with `LIKE` only for single-object, indexed-field72 matches. Both with `WITH USER_MODE` and73 `@AuraEnabled(cacheable=true)`. `WITH USER_MODE` is GA from API74 57.0; the clause it replaces, `WITH SECURITY_ENFORCED`, no75 longer compiles at 67.0+ (Summer '26).763. **Debounce the search by 250-300ms.** Use `setTimeout` /77 `clearTimeout` in the input's `oninput` handler. Without78 debounce, every keystroke fires a callout — exhausting Apex CPU79 and pinning the org.804. **Build the open/close state machine.** Three states: closed,81 open-with-search-loading, open-with-results. Open on focus,82 close on blur (with a 200ms delay so result clicks land83 first), close on escape, close on selection.845. **Implement keyboard navigation.** Arrow up/down move85 `activeIndex`, Enter selects, Escape closes. Render86 `aria-activedescendant` on the input pointing at the result li87 so screen readers track focus.886. **Render the selected state as a pill.** Once chosen, swap the89 input for an SLDS pill (`<lightning-pill>`) with a remove90 action. Re-clicking the remove returns to search mode.917. **Cache the SObject icon.** `getObjectInfo` gives the icon URL;92 prepend it to results once per render rather than per result.9394## What This Skill Does Not Cover9596- **Lookups inside `lightning-record-edit-form`** — use97 `lightning-input-field` and configure lookup filters in metadata.98- **`lightning-record-picker` (standalone, Spring '24+)** — see99 `lwc/lwc-record-picker`.100- **Lookup filters at the field-metadata level** — see101 `admin/lookup-filter-design`.102- **Type-ahead against external systems** — see103 `integration/external-search-via-named-credential`.