Lookup Dialog
The Lookup Dialog is the Salesforce UI component that opens when a user clicks the magnifying-glass icon next to a lookup field, letting them search for and select a related record.
Definition
The Lookup Dialog is the Salesforce UI component that opens when a user clicks the magnifying-glass icon next to a lookup field, letting them search for and select a related record. The dialog presents a search box, recent records, and search results filtered to the related object''s scope. In Lightning Experience, the Lookup Dialog renders as a typeahead dropdown beneath the field with real-time search results and supports keyboard navigation. In Salesforce Classic the dialog opens as a modal popup.
The Lookup Dialog is the everyday way users link records together. Picking a Contact on an Opportunity, an Account on a Case, a Product on an Order all use the lookup dialog. The dialog respects record sharing (users see only records they have access to), lookup filters (admins narrow the dialog''s scope to relevant records), and search behavior (the dialog uses Salesforce search, which indexes name and selected other fields). Configuring lookup dialogs well is one of the highest-leverage UX improvements an admin can make.
How Lookup Dialog behavior shapes record-linking UX
Typeahead vs. Classic modal
Lightning Experience renders the Lookup Dialog as a typeahead dropdown: the user types, the dialog shows matching results inline. Salesforce Classic uses a modal popup with search and recent records. The Lightning experience is faster for users who know what they''re looking for; the Classic modal is more visible for users who need to browse.
Search behavior
The Lookup Dialog uses Salesforce search to find matching records. Search indexes the record''s Name field by default, plus selected other fields (Email, Phone) if admins enable them via Search Index Settings. The dialog respects record sharing; users see only records they have access to.
Lookup filters
Admins configure lookup filters on fields to narrow the records shown in the dialog. A filter like Account.Type = ''Customer'' on the Opportunity.AccountId field restricts the dialog to customer accounts only. Lookup filters are powerful UX improvements; they prevent users from picking the wrong record by hiding irrelevant ones.
Default search scope per object
The Lookup Dialog shows results scoped to the target object of the lookup field. A Contact lookup on Opportunity shows only Contacts. The dialog also respects record types: if the lookup field is record-type-aware, results filter to the matching record types.
Recent records and frequently-used
The dialog shows recent and frequently-used records when no search is entered. The list pulls from the user''s recent activity. This is a useful default for users who repeatedly link to the same handful of records.
Create-new from lookup
The Lookup Dialog includes a New button (often as +New) letting users create the target record inline without navigating away. The new record is created with whatever required fields the page layout exposes; once saved, the new record auto-fills into the lookup field. This is the standard pattern for creating related records mid-workflow.
Custom Lookup search behavior
Admins can configure which fields are searchable and which fields display in the Lookup Dialog''s result rows. Setup, Search, Search Layouts let admins pick the fields shown in the dialog (Name, Type, City, Owner). A well-configured search layout dramatically improves the user''s ability to pick the right record.
Configure Lookup Dialog behavior on a field
Lookup Dialog customization runs through field configuration plus the object''s search layout. The combination is what shapes user UX.
- Identify the lookup field
Setup, Object Manager, the source object, Fields & Relationships, click the lookup field.
- Configure a lookup filter (optional)
Edit the field, add lookup filter criteria to scope the dialog''s results.
- Configure the search layout
Setup, Object Manager, the target object, Search Layouts, edit the Lookup Dialogs layout. Pick the fields shown in the result rows.
- Enable search on additional fields
Setup, Search, Search Index Settings, enable additional fields (Email, Phone) on the target object for search.
- Test the lookup behavior
Open a record with the lookup field, click the magnifier or type in the field. Verify the right results appear with the right columns.
- Iterate based on user feedback
Users notice lookup dialogs that show the wrong fields or that include too-broad results. Tighten lookup filters and adjust search layouts based on feedback.
- Lookup Dialogs respect record sharing. Users see only records they have access to; integrations should not assume users will see all records.
- Lookup filters can be too restrictive. A filter that hides legitimate records produces user frustration and workaround behavior.
- Search layouts are per-object, not per-lookup-field. Changing the layout affects every lookup dialog targeting that object.
- Lightning typeahead is faster but less discoverable than the Classic modal. New users sometimes miss the dropdown.
Trust & references
Cross-checked against the following references.
- Lookup FiltersSalesforce Help
- Lookup Dialog BehaviorSalesforce Help
Straight from the source - Salesforce's reference material on Lookup Dialog.
- Search LayoutsSalesforce Help
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Test your knowledge
Q1. What is the Lookup Dialog?
Q2. What's the modern Lightning equivalent?
Q3. What can restrict which records appear?
Discussion
Loading discussion…