Overlay
An overlay in Salesforce is a panel that opens on top of the current page so a user can view or work with extra information without leaving the screen they are on.
Definition
An overlay in Salesforce is a panel that opens on top of the current page so a user can view or work with extra information without leaving the screen they are on. It floats above the page content as a dialog or popup, keeps the work behind it in place, and closes to return the user to exactly where they were.
Overlay is mostly a legacy term tied to the original Salesforce Console in Classic, where detail records and custom-link targets could open in a floating panel. The same idea lives on in Lightning, but it is delivered through newer pieces such as console subtabs, split view, and the modal base components rather than the old console overlay itself.
How overlays show extra content without losing the page underneath
What an overlay actually is
An overlay is a layer of content drawn on top of the page the user is already looking at. The page behind it stays loaded and in the same state, and a shaded backdrop usually dims it so the eye goes to the panel. When the user finishes, the overlay closes and the original page is right there, unchanged. That is the whole point: show something extra, then get out of the way. Salesforce has used overlays in several places over the years. In the Salesforce Console for Classic, clicking certain links could open a record detail or a custom-link target in a floating panel instead of replacing the page. On record pages, inline edit and lookup search results have used small overlay panels. In Aura components, the overlay library produced modals and popovers on demand. The common thread is layering, not navigation. A normal link sends the user somewhere new, while an overlay keeps them put and stacks the new content above the old. That difference matters for agents who need their place held while they glance at a related record.
Overlays in the Salesforce Console (Classic)
The original Salesforce Console in Classic was built so support agents could keep a primary record open and pull related records into tabs without losing context. Overlays were part of that design. A custom link or button on a detail page could be set to open its target in a floating window layered over the console, and some console interactions surfaced record detail in a popup-style panel rather than a full page load. This fit the console job well. An agent on a case did not want a link to throw them onto a different screen and break their train of thought. An overlay let them peek at an account, a contact, or an external page, read what they needed, and dismiss it. The console also offered list-view and detail behaviors that opened records in primary tabs and subtabs, so overlays were one tool among several for staying in flow. Because this console lived inside Salesforce Classic, the overlay behavior is now a Classic-era pattern. Teams that have moved to Lightning Experience no longer rely on it, even though the underlying need to hold context is still very real.
Custom buttons, links, and display behavior
A lot of overlay behavior in Classic came from how a custom button or link was configured. When you build one in Setup, you choose a display behavior that controls where the target appears. Options include opening in a new window, in the existing window with the sidebar, in the existing window without the sidebar, and without the sidebar or header. Pairing those behaviors with window properties decided whether a link replaced the page, took over the frame, or popped up over it. In the Classic console, that configuration is what made a link feel like an overlay. The display window properties let an admin keep the target compact and layered instead of sending the agent off to a fresh page. This is admin work, not code, which is why overlay shows up in administration material rather than only developer guides. It is worth knowing that these display-behavior choices were tuned for Classic. In Lightning Experience, several of the same options are ignored or behave differently, so an admin migrating buttons cannot assume an old overlay setting will carry over unchanged.
The Aura overlay library for developers
On the developer side, overlay had a concrete component: the overlay library, used in Aura with the lightning:overlayLibrary tag. It gave components two things. A modal opened a dialog in the foreground and blocked interaction with the rest of the app until the user acted on it or dismissed it. A popover showed contextual content next to a reference element without blocking the page, handy for hints and small details on hover or click. You included one overlayLibrary tag in a component, gave it an aura:id, and then called methods like showCustomModal or showCustomPopover from the controller. The modal supported a header, body, and footer, plus a close callback, while the popover was lighter and styled mainly through its body and CSS. There were helpers to close an overlay directly or to fire a notifyClose event from a component that did not open it. Salesforce now marks the overlay library as a legacy component. The guidance is explicit: it is for Aura only, and Lightning Web Components should use the modal module instead. That makes the overlay library another piece of the legacy overlay story.
What replaced overlays in Lightning
Lightning Experience did not drop the need to show extra content in place. It met it with newer building blocks. The Lightning console keeps agents focused through workspace tabs and subtabs, pinned regions, and split view, so a related record opens beside or under the primary one without a full navigation away. Quick actions and component-driven panels let users create or edit records from the highlights panel without leaving the page. For dialogs specifically, Lightning Web Components use the LightningModal base component from the lightning/modal module. Instead of dropping a tag on the page, you extend LightningModal in your class and launch it with the open method. The template is built from lightning-modal-body, which is required, plus optional lightning-modal-header and lightning-modal-footer. The modal overlays the page, traps focus, and blocks the rest of the app until it is dismissed, following the Salesforce Lightning Design System modal pattern. So the overlay concept survives, just under different names and with better accessibility and design consistency than the old console overlay offered.
Why the distinction still matters today
You will still run into the word overlay, and knowing what it points to saves confusion. In old documentation, knowledge articles, or an inherited org, an overlay reference almost always means the Classic console floating panel or a custom-link display behavior set up for that console. If you are reading developer material, overlay likely means the Aura overlay library and its modals and popovers. Both are signals that you are looking at older patterns. When you plan or modernize, translate the intent rather than the mechanism. The real requirement is usually contextual access: let a user see or touch a secondary record without losing the page in front of them. In Lightning, you satisfy that with subtabs and split view in the console, quick actions on the record page, and LightningModal in custom components. Treat an overlay reference as a prompt to ask what context the user was trying to preserve, then pick the modern equivalent. That keeps the behavior intact while moving the implementation onto supported, current tools.
Set up an overlay-style custom button or link
The closest admin equivalent of classic overlay behavior is a custom button or link whose display behavior opens its target in a layered window rather than replacing the page. Here is how to set one up in Setup. Remember that several display behaviors were designed for Salesforce Classic and may behave differently in Lightning Experience, so test in the environment your users actually use.
- Open the object's Buttons, Links, and Actions
In Setup, go to the Object Manager, pick the object (for example Case or Account), and open Buttons, Links, and Actions. Click New Button or Link to start a fresh definition.
- Choose the display type
Set the display type to Detail Page Link or Detail Page Button so it appears on the record. The display type decides where the control shows up, while the behavior decides how the target opens.
- Set the display behavior
Pick a behavior such as Display in existing window without sidebar or header. This is the setting that, paired with window properties, gives the layered, overlay-like result instead of a full page replacement.
- Define the content and add it to the layout
Enter the URL or content source for the target, save, then edit the page layout and drag the button or link into the layout so users can see it. Confirm it renders where you expect.
Detail Page Link or Detail Page Button so the control sits on the record's detail page.
Where the target opens, such as a new window or the existing window without the sidebar or header.
Sizing and chrome of the opened window, which combine with Behavior to produce a layered, popup-style result.
URL, OnClick JavaScript (Classic only), or Visualforce page that supplies what the overlay shows.
- Several display behaviors were built for Salesforce Classic and are ignored or act differently in Lightning Experience, so always test in the user's real interface.
- OnClick JavaScript buttons do not run in Lightning Experience; rebuild that logic as a quick action, screen flow, or Lightning component.
- For new custom UI, build a dialog with the LightningModal base component instead of trying to recreate the old Aura overlay library.
Prefer this walkthrough as its own page? How to Overlay in Salesforce, step by step
Trust & references
Cross-checked against the following references.
Straight from the source - Salesforce's reference material on Overlay.
Hands-on resources to go deeper on Overlay.
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. In the Salesforce Classic console, what does an Overlay let an agent do?
Q2. Which Lightning Experience patterns replaced the Classic console Overlay for working with secondary records?
Q3. What does an Overlay preserve when an agent opens a related record from the current page?
Discussion
Loading discussion…