Lookup Dialog
A Lookup Dialog is the Salesforce search interface that opens when a user fills a lookup field, letting them find and pick a related record.
Definition
A Lookup Dialog is the Salesforce search interface that opens when a user fills a lookup field, letting them find and pick a related record. It appears when you click into or beside a lookup field on a record page, presenting a search box, a list of suggested records, and matching results scoped to the field's target object.
In Lightning Experience the dialog renders as a typeahead dropdown beneath the field. As the user types, results adjust to records whose Name matches what they entered, drawn from recent items, frequently used objects, and the current object. In Salesforce Classic the same idea appears as a modal popup. The dialog respects record-level sharing, so users see only records they can access, and it respects lookup filters that an admin sets to narrow the field's scope.
How the Lookup Dialog finds and shows records
Typeahead in Lightning, modal in Classic
The Lookup Dialog looks different depending on the experience, but the job is the same: find one related record and put it in the field. In Lightning Experience it is a typeahead dropdown. The user clicks the field, and a panel drops down with suggestions. As they type, the list narrows in real time, and they can move through it with the arrow keys and select with Enter. There is no separate popup window to open or close, which keeps record creation flowing. Salesforce Classic shows the dialog as a separate modal popup, often opened by the magnifying-glass icon next to the field. The popup has its own search box and a list of recent records, and the user picks a result to send it back to the field. The Classic modal is more visible and gives more room to browse, while the Lightning typeahead is quicker for users who already know the record they want. Both versions enforce the same access rules, so the visual difference does not change which records a given user can see.
Name-only suggestions, then advanced search
The instant suggestions in a Lightning lookup search only the Name field. If a user types "Acme" into an Account lookup, the dropdown matches accounts whose Name contains that text, not accounts whose description or billing city contains it. The one documented exception is when the object's Name is an auto-number; in that case search behaves differently because there is no text name to match against. This name-only behavior surprises admins who expect a lookup to find a record by email or phone. To search wider, the user types at least two characters and clicks "Show more results", which opens an advanced search window. Advanced lookup search goes through all searchable fields on the record, not just Name, and sorts results by relevance. So the typeahead is fast and narrow, and the advanced window is slower and broad. Knowing the split helps you guide users: tell them to type a few letters of the record name first, and reach for "Show more results" when they only have something like an email address to go on.
Recent and frequently used records
Before the user types anything, the Lightning Lookup Dialog already shows suggestions. These come from recent items, items from the user's most frequently used objects, and items from the object the field points to. For someone who keeps linking the same Account to new Cases all week, that Account tends to sit right at the top, so the field fills in a couple of clicks. There is a quirk worth knowing. A record joins the recent items list when you create or edit it, not simply when you view it in some contexts. If a user cannot find a freshly created record in the dropdown, the documented fix is to end the current session and start a new one, which refreshes the recent list. The fields shown for each suggestion are not random either. They come from the search results layout for that object, so the secondary line under the record name (a phone number, an account, a city) is something an admin chose. A good secondary field is the difference between picking the right "John Smith" and guessing.
Search layouts decide which columns appear
What the user sees in each result row is controlled by a search layout, configured per object in Setup. In Lightning Experience the relevant layout is Search Results, found under Object Manager, the object, then Search Layouts. The fields you add there drive both global search results and the lookup suggestions, so you do not maintain a separate Lightning lookup layout. Salesforce Classic still exposes a distinct Lookup Dialogs search layout for the same purpose. This matters because the default is thin. A Contact lookup that shows only Name forces the user to recognize people by name alone, which fails the moment two contacts share a name. Add Account Name, Email, and Title to the Search Results layout, and each suggestion becomes self-explaining. The dialog typically shows a primary line (the record name) and a secondary line built from these layout fields, with more visible when the row is expanded. Spend a few minutes setting sensible columns on your high-traffic objects, because this single change removes a lot of "wrong record" data errors without any code.
Lookup filters and dependent lookups narrow the scope
By default a lookup shows every record of the target object that the user can access. That is often too many. A lookup filter is admin-defined criteria on the field that restricts which records the dialog offers. A filter such as Account Type equals Customer on an Opportunity's Account field hides prospect and partner accounts, so users only see and select customers. Filters can be required, which blocks a save when the chosen record fails the criteria, or optional, which lets users toggle the filter off. A dependent lookup is a special, useful case: a lookup filter that references a field on the current record. On a Case, you can filter the Contact field so it only offers contacts related to the Account already chosen on that Case. The dialog's choices then change based on what the user picked earlier on the same page. Salesforce Classic also has enhanced lookups, where an admin specifies up to six Lookup Filter Fields that users can filter the popup by at search time. Configuring Application is the permission needed to set these up.
Sharing and record types still apply
The Lookup Dialog is never a way around your security model. It runs through the same access rules as the rest of the platform, so a result only appears if the searching user has at least read access to it through org-wide defaults, role hierarchy, sharing rules, or manual shares. An admin building a page sees a far wider set of records than a restricted sales rep will, which is why a lookup that looks complete to you can come up empty for someone else. Record types fold in as well. If the target object uses record types, the records offered can be limited to the ones that fit the context, so a user is not handed choices that would not make sense for the record they are editing. The practical takeaway is to test lookups while logged in as, or impersonating, a restricted-profile user. What the dialog returns for that user is the real experience. Checking it as an admin gives a false sense that everything resolves, when a sharing gap or a missing record-type assignment may be quietly hiding the very record the user needs.
The modern building block: lightning-record-picker
When developers need lookup behavior inside a custom screen or Lightning web component, the current building block is lightning-record-picker. It implements the same autocomplete combobox lookup pattern from the Salesforce Lightning Design System, so users get a familiar typeahead, but you control it with attributes instead of page-layout config. Under the hood it uses the GraphQL wire adapter to fetch matching records rather than the older SOSL path. A few attributes mirror what admins tune on a standard lookup. The required object-api-name sets which object to search. The filter attribute defines which records the picker lists, using criteria and optional filter logic, including cross-object references like Account.Phone. The matching-info attribute names which fields the search term is matched against, and display-info shapes how each suggestion looks in the dropdown. So the same three levers exist in declarative and programmatic form: what object, which records, and what shows. If you have outgrown the standard lookup on a record page and need a lookup on a custom UI, this component is the supported route, and it keeps the look and the access checks consistent with the platform.
Configure what a Lookup Dialog shows
You do not create a Lookup Dialog. It appears automatically on every lookup field. What you configure is what it shows and which records it offers. The two highest-value settings are the Search Results search layout (columns) and lookup filters (scope), both per object in Setup.
- Open the object's Search Layouts
In Setup, go to Object Manager and select the object whose lookup you want to improve, for example Contact. Click Search Layouts, then find the Search Results layout used by Lightning Experience. In Salesforce Classic, edit the Lookup Dialogs layout instead.
- Add meaningful result columns
Edit the Search Results layout and move fields such as Account Name, Email, and Title from Available to Selected. These become the secondary details under each suggestion, so users can tell similar records apart. Save the layout.
- Add a lookup filter to the field
Go to the lookup field itself (Fields and Relationships, then the field, then Edit). Define a Lookup Filter, for example Account Type equals Customer, to limit which records the dialog offers. Decide whether the filter is Required or Optional.
- Make it dependent where it helps
For a dependent lookup, set the filter to reference a field on the current record, such as limiting a Case Contact to the Case's Account. This narrows the dialog based on earlier choices on the same page.
- Test as a restricted user
Log in as, or impersonate, a user on a limited profile and open the lookup. Confirm the right records appear and the columns read well. Sharing and filters can hide records that an admin sees, so verify the real user experience.
Per-object layout in Object Manager that sets which fields show in Lightning lookup suggestions and global search. Classic uses a separate Lookup Dialogs layout.
Admin-defined criteria on the field that restrict which records the dialog offers. Can be Required (blocks an invalid save) or Optional (user can toggle it off).
A lookup filter that references a field on the current record, so the dialog's choices depend on a value already entered on the same page.
Up to six Lookup Filter Fields an admin specifies so users can filter the Classic enhanced lookup popup at search time. Needs the Customize Application permission.
- Lightning typeahead matches the Name field only. Users searching by email or phone must click Show more results to run an advanced search across all searchable fields.
- A newly created record may not appear in recent items until the user starts a new session, because records enter the recent list when created or edited.
- In Lightning Experience there is no separate Lightning lookup layout; the Search Results layout drives both lookup suggestions and global search, so changes affect both.
- The dialog enforces sharing. A record an admin can see may be invisible to a restricted user, so always test lookups under a limited profile.
Trust & references
Cross-checked against the following references.
- Lookup Search in Lightning ExperienceSalesforce
- Lookup Search Cheat SheetSalesforce
Straight from the source - Salesforce's reference material on Lookup Dialog.
- Specify Lookup Search Filter FieldsSalesforce
- lightning-record-picker Component ReferenceSalesforce
Hands-on resources to go deeper on Lookup Dialog.
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…