Build Custom Lookup Field in Aura for Salesforce CPQ
Why use a Custom Lookup Field in Aura for Salesforce CPQ?
In Salesforce CPQ, out‑of‑the‑box lookup fields are useful but often restrictive. They usually support only standard objects, fixed filters, and limited search behaviours, which may not fit complex quotations or product configuration workflows. To bridge this gap, many CPQ implementations build custom lookup fields inside Aura components to provide users more control over which records appear, how they are searched, and how they relate to quote lines, products, or configuration steps.
A custom lookup in Aura is essentially a reusable component that lets a user type in a search term, fetch matching records from an object (standard or custom), and select one to populate a lookup‑style field on the page. When integrated with CPQ, this lookup can set values on quote lines, products, bundles, or configuration attributes, making the quoting flow more dynamic and data‑driven.
Table of Contents
Core Concepts Behind Aura and CPQ Lookups
Aura components are client‑side Lightning components built with HTML‑like markup, JavaScript controllers, helper files, and Apex controllers. They run inside Lightning Experience or Lightning Pages or are embedded in CPQ interfaces such as line editors or custom configurators.
A lookup field in Salesforce is a reference field that links one record to another, typically via a lookup relationship. In CPQ, lookups often connect objects like a quote line, price rule, product, or configuration attribute to related records such as accounts, contacts, products, custom objects, or external data.
A custom Aura lookup recreates this behaviour in code, so developers can:
- Support any object (not just standard).
- Use custom filters and SOQL queries.
- Show rich picklists or multiple columns in search results.
- Integrate with external data sources or joined datasets.
Planning the Custom Lookup Design
Before writing codes, teams usually define the following:
- Source object: Which object the lookup will search (e.g., a custom “Pricing Tier” object).
- Target field: Which CPQ field this lookup will populate (e.g., a standard or a custom field).
- Search behaviour: whether the user searches by name, code, or multiple fields, and whether the results should be filtered based on the current quotation, account, or other context.
- Reusability: Whether the component should be generic enough to be reused across multiple CPQ pages or objects.
This design helps you decide:
- What attributes are to be exposed (e.g., …)?
- This is how the Apex controller will query records.
- This section explains how the Aura component receives and emits the selected record.
Apex Controller for the Lookup
The backbone of a custom Aura lookup is an Apex controller with @AuraEnabled methods. This class is responsible for:
- This class is responsible for receiving search parameters, including object name, search string, parent record ID, and filters.
- This class is responsible for constructing a dynamic SOQL or optimised query that retrieves matching records.
- Return a list of records or a structured wrapper class (often called
RecordsDataa record) that includes at least an ID, name, and any other fields needed for display.
Typical patterns seen in such controllers include:
- Taking arguments like… to dynamically construct WHERE-clause conditions.
- Use proper query escapes to prevent injection risks.
- Optionally supporting parent‑child relationships, such as loading only Contacts related to a selected Account, which is useful for dependent lookups in CPQ configuration flows.
This Apex layer is then referenced from the Aura component using the controller attribute on <aura:component>.
Aura Component Structure
The Aura component typically consists of:
- Attributes that define configuration and state.
- HTML markup that renders the input and dropdown/list.
- JavaScript controller and helper methods that handle keypresses, search, and selection.
Common attributes include:
objectName– object API name to search (e.g.,"Account"or"Product2").fieldName– the API name of the CPQ field that will store the selected ID.value– the current record ID (for pre‑populating an existing value).searchStringThis parameter refers to what the user types in the search box.records– the list of matching records returned from Apex.selectedRecord– the chosen record object attached to the component.
The markup usually includes the following:
- Or
<ui:inputText>for the search. - A dropdown or
<aura:iteration>list of results that shows names, codes, or other fields. - Optional elements like a “clear” button or spinner while the server is being queried.
When the user types, the component debounces the input, fires a @AuraEnabled method, and updates the records list once the response arrives.
JavaScript Logic in Aura
The client-side JavaScript handles the following:
- Debouncing keystrokes to avoid firing too many server calls.
- Calling the Apex method with current parameters.
- Updating the UI with results.
- Handling record selection and broadcasting the chosen record back to CPQ.
Typical controller methods:
onSearchInput– listens for changes in the search field, starts a timer, and calls Apex after a short delay.doSearch– invokes the Apex@AuraEnabledmethod, passes the search string and other parameters, and assigns the result.onRecordSelect– Fires when the user clicks a search result; it setsselectedRecordand then raises an event or calls a parent component’s handler to update the actual CPQ field.
In many designs, the component uses an event (either a custom aura:event or a generic one) to notify the surrounding CPQ page or another component that a record has been selected so that the parent can update quote lines, reload rules, or refresh pricing.
Integrating the Lookup into Salesforce CPQ
To plug this custom Aura lookup into CPQ, developers typically:
- Embed the Aura component inside a CPQ Lightning Page or a custom button/component that opens from the Quote Line Editor, Configuration, or Product Selection pages.
- Bind the component
fieldNameto the relevant CPQ field so that selecting a record from the lookup updates the line or configuration. - Ensure the component respects record‑type context, user permissions, and filtering by the current quote’s account or status where appropriate.
For example, a CPQ designer might:
- Create a custom picklist or lookup in the Product or Quote Line object meant to store a custom pricing tier.
- Use the Aura custom lookup to let the user search for tiers filtered by the selected product family or account.
- Ensure that the CPQ price rules or configuration logic read this field and adjust the price, discounts, or bundled items accordingly.
This approach allows dynamic, context‑aware lookups that standard CPQ lookup fields often cannot provide.
Dynamic and Dependent Lookup Filtering
A powerful enhancement is dynamic and dependent filtering. For instance:
- The first custom lookup selects an account.
- The second lookup then only shows contacts associated with that account.
This is achieved by:
- Passing the
parentRecordId(e.g., Account ID) from the first lookup into the second lookup’ssearchmethod. - Modify the SOQL where-clause in Apex to include a condition like this.
In a CPQ context, the same pattern can be applied to the following:
- Only show products valid for a specific account or market.
- Only display price dimensions or discounts that are active for the current quote’s currency or date range.
Such dynamic filtering drastically improves user experience and reduces the risk of invalid selections that break pricing or validation rules.
User Experience and Usability Considerations
For a CPQ‑focused custom lookup, UX is critical because users often work in fast‑paced quoting scenarios. Common best practices include:
- Debouncing searches (e.g., wait 300–500 ms after typing) to avoid flooding the server with requests.
- Showing a spinner or loading indicator when the search is in progress so users know the system is working.
- Limiting results (e.g., top 25–50 records) to keep the UI fast and readable.
- Supporting keyboard navigation (up/down arrows, Enter/Escape) for power users.
In CPQ, additional UX considerations:
- Ensure the lookup modal or dropdown does not interfere with the main quote line editor layout.
- Align styles with the organization’s Lightning theme, so the custom component feels native.
Performance and Security Best Practices
Because the custom lookup queries Salesforce data, performance and security must be addressed:
- Query optimisation: Use selective filters, leverage indexes, and avoid querying all fields when only a few are needed for display.
- Governor limits: Be mindful of SOQL query limits, especially when using the lookup in bulk or in multi‑select scenarios.
- SoQL injection: Avoid concatenating raw user input into queries; instead, use bound variables or parameterised patterns.
- Field‑level security and sharing: Ensure the Apex controller runs in the context of the current user so that only records the user can see are returned.
In CPQ, these points are especially important when the lookup is tied to price rules, validations, or configuration logic, since any delay or error can disrupt the quoting flow.
Extending to External Data and Salesforce Connect
Beyond local Salesforce objects, custom Aura lookups can also integrate with external data sources via Salesforce Connect or external objects. For example:
- A CPQ lookup might search products or pricing in an external ERP system exposed as external objects.
- The Apex controller can query those external objects in the same way it would query standard or custom objects, as long as the external data source is configured correctly.
This allows:
- Real‑time access to external pricing catalogues without duplicating data into Salesforce.
- CPQ users can select products or tiers that are managed and updated in a different system.
However, additional latency and licensing considerations should be evaluated when using external data in high‑frequency CPQ workflows.
Summary
Building a custom lookup field in Aura for Salesforce CPQ provides teams the flexibility to connect CPQ objects to any internal or external data source while maintaining a smooth, fast, and context‑aware user experience. By using an Apex controller with dynamic SOQL, an Aura component that manages smart searches, and careful integration into CPQ pages and processes, organisations can enhance standard CPQ features to handle complicated quoting situations that regular lookups can’t manage.
