Salesforce Lookup Component (Aura version, maintenance only)

⚠️This Aura version is no longer maintained.
New features are only added to the Lightning Web Component version.

About

This is a generic & customizable lookup component built using Salesforce Lightning (Aura) and SLDS 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
• built-in server request rate limit mechanism

Documentation

The lookup component is documented using Aura documentation.
You can access it from this URL (replace the domain):
https://<YOUR_DOMAIN>.lightning.force.com/docs/component-library/bundle/c:Lookup/documentation

Follow these steps in order to use the lookup component:

Basic use

1) Write the search endpoint

Implement an Apex @AuraEnabled method (SampleLookupController.search in our samples) that returns the search results as a List<LookupSearchResult>. The method name can be different but it needs to match this signature:

@AuraEnabled
public static List<LookupSearchResult> search(String searchTerm, List<String> selectedIds) {}

2) Handle the search event and pass the results to the lookup

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

<c:Lookup selection="{!v.selection}" onSearch="{!c.lookupSearch}" label="Search"/>

The event handler should do the following:

lookupSearch : function(component, event, helper) {
    // Get the lookup component that fired the search event
    const lookupComponent = event.getSource();
    // Get the Apex server-side action associated with this search (`search` in our samples)
    const serverSearchAction = component.get('c.search');
    // Passes the action to the lookup component by calling the `search` aura method
    lookupComponent.search(serverSearchAction);
}

Advanced use case: custom search parameters

If you need to pass custom parameters like a record id to the Apex search method, you can write the following search event handler:

lookupSearch : function(component, event, helper) {
    // Get the lookup component that fired the search event
    const lookupComponent = event.getSource();
    // Get the SampleLookupController.search server side action
    const serverSearchAction = component.get('c.search');
    // You can pass optional parameters to the search action
    // but you can only use setParam and not setParams to do so
    serverSearchAction.setParam('recordId', component.get('v.recordId'));
    // Passes the action to the Lookup component by calling the search method
    lookupComponent.search(serverSearchAction);
},

And use a custom Apex search method with your extra parameters:

@AuraEnabled(cacheable=true)
public static List<LookupSearchResult> search(String searchTerm, List<String> selectedIds, String recordId) {

}

Advanced use case: lookups in an iteration

If you use lookups in an iteration and need to adjust the search logic based on some iteration parameter, follow these steps.

Wrap the Lookup in a div with a dynamic dataset attribute like so:

<aura:iteration items="{!v.rows}" var="row" indexVar="index">
  <div data-row-index="{!index}">
    <c:Lookup .../>
  </div>
<aura:iteration>

Then, in your search function, do that:

lookupSearch : function(component, event, helper) {
  // Get the lookup component that fired the search event
  const lookupComponent = event.getSource();
  // Get the row index from the parent div
  const rowIndex = lookupComponent.getElement().parentNode.dataset.rowIndex;

  // Handle the rest of the search logic
  // You can use different search endpoints depending on the row index for example
}

Salesforce DX setup instructions

Deploy the sample application with the Salesforce CLI.

Sample application

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, edit sfdx-project.json and remove the src-sample path.