SfSkills Domains Docs GitHub

Home / lwc / lwc-custom-lookup

lwc-custom-lookup

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.

Open the skill folder on GitHub

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:

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.

  1. 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.

  2. 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).

  3. 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.

  4. 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.

  5. 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.

  6. 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.

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

Package files