Repository files navigation

Now compatible withSLDS 2!

^* Forward-Looking Statements. No estimated date of delivery or guarantees.

1. About
2. Installation
3. Documentation
   1. Getting started
   2. Handling selection changes (optional)
   3. Providing default search results (optional)
   4. Saving form state when creating new records (optional)
   5. Passing custom data to JavaScript and Apex (optional)
4. Reference
5. Special use cases
   1. Working with picklists values

This is a generic & customizable lookup component built using SalesforceLightning Web Components andSLDS style.
It does not rely on third party libraries and you have full control over its datasource.

Features

The lookup component provides the following features:

• customizable data source that can return mixed sObject types
• single or multiple selection mode
• client-side caching & request throttling
• great test coverage
• full accessibility (a11y) compliance
• keyboard navigation
• search term highlighting
• ability to create new records

The default installation installs the lookup component and a sample application available under this URL (replace the domain):
https://YOUR_DOMAIN.lightning.force.com/c/SampleLookupApp.app

If you wish to install the project without the sample application, editsfdx-project.json and remove thesrc-sample path.

Install the sample app by running this script:

MacOS or Linux

./install-dev.sh

Windows

install-dev.bat

Follow these steps to use the lookup component:

1. Write the search endpoint

   Implement an Apex@AuraEnabled(cacheable=true scope='global') method (SampleLookupController.search in our samples) that returns the search results as aList<LookupSearchResult>.The method name can be different, but it needs to match this signature:

   @AuraEnabled(cacheable=truescope='global')publicstaticList<LookupSearchResult>search(StringsearchTerm,List<String>selectedIds) {}

2. Import a reference to the search endpoint

   Import a reference to thesearch Apex method in the lookup parent component's JS:

   importapexSearchfrom'@salesforce/apex/SampleLookupController.search';

3. Handle the search event and pass search results to the lookup

   The lookup component exposes asearch event that is fired when a search needs to be performed on the server-side.The parent component that contains the lookup must handle thesearch event:

   <c-lookuponsearch={handleSearch}label="Search"placeholder="Search Salesforce"></c-lookup>

   Thesearch event handler calls the Apexsearch method and passes the results back to the lookup using thesetSearchResults(results) function:

   asynchandleSearch(event){constlookupElement=event.target;try{constresults=awaitapexSearch(event.detail);lookupElement.setSearchResults(results);}catch(error){// TODO: handle error}}

The lookup component exposes aselectionchange event that is fired when the selection of the lookup changes.The parent component that contains the lookup can handle theselectionchange event:

<c-lookuponsearch={handleSearch}onselectionchange={handleSelectionChange}label="Search"placeholder="Search Salesforce"></c-lookup>

Theselectionchange event handler can then get the current selection from the event detail or by calling thegetSelection() function:

handleSelectionChange(event){// Get the selected ids from the event (same interface as lightning-input-field)constselectedIds=event.detail;// Or, get the selection objects with ids, labels, icons...constselection=event.target.getSelection();// TODO: do something with the lookup selection}

getSelection() always return a list of selected items.That list contains a maximum of one element if the lookup is a single-entry lookup.

The lookup can return default search results with thesetDefaultResults(results) function. This is typically used to return a list of recently viewed records (see sample app).

Here's how you can retrieve recent records and set them as default search results:

1. Implement an Apex endpoint that returns the recent records:

   @AuraEnabled(cacheable=truescope='global')publicstaticList<LookupSearchResult>getRecentlyViewed()

   See thefull code from the sample app

2. In your parent component, create a property that holds the default results:

   recentlyViewed=[];

3. Write a utility function that sets your default search results:

   initLookupDefaultResults(){// Make sure that the lookup is present and if so, set its default resultsconstlookup=this.template.querySelector('c-lookup');if(lookup){lookup.setDefaultResults(this.recentlyViewed);}}

4. Retrieve the recent records by calling your endpoint:

   @wire(getRecentlyViewed)getRecentlyViewed({ data}){if(data){this.recentlyViewed=data;this.initLookupDefaultResults();}}

5. Initialize the lookup default results when the parent component loads:

   connectedCallback(){this.initLookupDefaultResults();}

The lookup component allows the user to create new record thanks to the optionalnewRecordOptions attribute. When users create a new record, they navigate away to the record edit form and they lose their current form input (lookup selection and more).

To prevent that from happening, you may provide an optional callback that lets you store the lookup state before navigating away. To do that, initialize the lookup new record options with apreNavigateCallback when the parent component loads:

connectedCallback(){/**     * This callback is called before navigating to the new record form     *@param selectedNewRecordOption the new record option that was selected     *@return Promise - once resolved, the user is taken to the new record form     */constpreNavigateCallback=(selectedNewRecordOption)=>{returnnewPromise((resolve)=>{// TODO: add some preprocessing (i.e.: save the current form state)// Always resolve the promise otherwise the new record form won't show upresolve();});};// Assign new record options with the pre-navigate callback to your lookupthis.newRecordOptions=[{value:'Account',label:'New Account', preNavigateCallback},{value:'Opportunity',label:'New Opportunity', preNavigateCallback}];}

Sometimes, you may want to pass extra data from the lookup component to Apex. To do so, usedataset attributes:

1. In the parent component that uses the lookup, add a dataset attribute (data-custom in this example):

   <c-lookupselection={initialSelection}onsearch={handleLookupSearch}label="Search"is-multi-entry={isMultiEntry}data-custom="My custom value">

2. In the parent JS, use the dataset attribute that you just added:

   handleLookupSearch(event){constlookupElement=event.target;alert(lookupElement.dataset.custom);// My custom value// Actual search code}

The lookup component can also be used to select values from picklist fields.

This Apex sample example demonstrates how you can query for the values ofAccount.Industry:

@AuraEnabled(cacheable=truescope='global')publicstaticList<LookupSearchResult>search(StringsearchTerm,List<String>selectedIds) {// Prepare query parameterssearchTerm='%'+searchTerm+'%';// Execute search queryList<PicklistValueInfo>entries= [SELECTLabel,ValueFROMPicklistValueInfoWHEREEntityParticle.EntityDefinition.QualifiedApiName='Account'ANDEntityParticle.QualifiedApiName='Industry'ANDisActive=TRUEANDLabelLIKE:searchTermANDValueNOT IN:selectedIdsLIMIT5    ];// Prepare resultsList<LookupSearchResult>results=newList<LookupSearchResult>();for (PicklistValueInfoentry:entries) {results.add(newLookupSearchResult(entry.Value,null,null,entry.Label,null));    }returnresults;}