Initializing/60 FPS
·4 min read

Unveiling the Magic of Angular CDK Overlay: Outside Pointer vs. Backdrop

Comparing outside pointer events and backdrops for closing floating UI panels in Angular CDK.

Kai Schönberger
Kai SchönbergerSoftware Engineer
AngularAngular CDKFrontendUI Architecture

The Angular CDK’s Overlay service is a powerful tool for creating floating panels and UI elements that appear on top of your application content. Whether it’s a dropdown menu, a modal dialog, or a custom tooltip, the Overlay provides the foundational building blocks to position and manage these elements effectively.

One crucial aspect of crafting a user-friendly overlay is determining how to close it when the user interacts outside of the overlay itself. The CDK offers two primary approaches for this: listening for outside pointer events or utilizing a backdrop. Both methods have their strengths and weaknesses, and understanding these nuances is key to choosing the right strategy for your specific use case. Let’s dive in and compare them.

The Responsive Lightness of Outside Pointer Events#

When you opt to close an overlay based on outside pointer events, you’re essentially attaching a listener to the global DOM that detects clicks or touches occurring outside the bounds of your overlay.

The Upsides:

  • Maintains Page Responsiveness: A significant advantage of this approach is that the rest of your application remains fully interactive. Users can still hover over elements, scroll the page, and generally interact with the underlying content even while the overlay is visible. This can lead to a smoother and less disruptive user experience for certain types of overlays, like context menus or tooltips that don’t necessarily need to block interaction with the rest of the UI. A typical use-case could be a context menu that opens on right click and if the user right clicks again while the menu is open, we want to immediately close the open menu and open a new instance at the clicked position.

The Downsides:

  • The Open-Close Dilemma: As highlighted in the notes, one common pitfall is the “open-close immediately” issue. If the trigger element for your overlay also resides within the bounds that are considered “outside” the overlay, a click on the trigger will first close the overlay (due to the outside pointer event) and then immediately reopen it (due to the trigger’s click event). This can lead to a frustrating flicker for the user or the feeling that the overlay didn’t close at all. You’ll need to implement logic to specifically filter out clicks originating from the trigger element to avoid this behavior. This is an issue with outsidePointerEvents observable but not with overlayOutsideClick output event of the cdkConnectedOverlay directive. The overlayOutsideClick output automatically filters clicks on the origin so that the origin can behave like a toggle.
  • Iframe Blind Spots: If your application or the overlay is embedded within an <iframe>, outside pointer events might not reliably bubble up to the parent document. This means a click inside the iframe but outside the overlay might not be detected, leaving the overlay stuck on the screen.
  • CDK Overlay Interactions: It appears that outside pointer event detection might not consistently trigger when a user clicks into another active CDK overlay. This could lead to unexpected behavior if you have multiple overlays stacked or interacting with each other.

The Blocking Power of a Backdrop#

The CDK Overlay also provides the option to render a backdrop element behind your overlay. This backdrop is a semi-transparent (or fully opaque) element that covers the entire viewport. When a user clicks on this backdrop, it can be configured to close the associated overlay.

The Upsides:

  • Simplified Stacking: Backdrops excel when dealing with multiple stacked overlays. Each overlay can have its own backdrop, and a click on a backdrop will typically only close the topmost overlay. This creates a clear and predictable interaction pattern for modal dialogs or layered interfaces.
  • Reliable Closure Across Iframes: Because the backdrop is part of the same document as the overlay, clicks on the backdrop will reliably trigger the close action, even if the interaction originates within an <iframe>.
  • Closing on Trigger Click (with caveats): When using a backdrop, a click on the trigger element itself will also trigger a backdrop click (as the backdrop covers the entire viewport, including the trigger). This inherently closes the overlay without the immediate reopening issue seen with outside pointer events. However, this also means you lose the ability to interact with the trigger element while the overlay is open.
  • Consistent Inter-Overlay Behavior: Since the backdrop sits between overlays, clicking outside the current overlay (and onto the backdrop of a lower overlay) will correctly close the current one.

The Downsides:

  • Blocks Underlying Interaction: The primary characteristic of a backdrop — covering the entire viewport — also means it blocks all interaction with the content behind it. This might not be desirable for less intrusive overlays like tooltips or simple dropdowns where you might want the user to still see and potentially interact with the underlying information.
  • Visual Overhead: Even a semi-transparent backdrop introduces a visual layer that might not always be aesthetically desired, especially for subtle overlays.

Making the Right Choice#

So, which approach should you choose? The answer, as is often the case, depends on the specific requirements of your overlay:

  • For lightweight, non-blocking overlays like context menus or simple dropdowns where maintaining the interactivity of the underlying content is crucial and you have a single overlay: Outside pointer events might seem appealing. However, be mindful of the potential “open-close immediately” issue and the complexities of filtering trigger clicks.
  • For modal dialogs, stacked overlays, or scenarios where you need to reliably close the overlay regardless of iframes and want to prevent interaction with the background: A backdrop is generally the more robust and straightforward solution. The blocking nature of the backdrop reinforces the modal behavior and simplifies event handling.

Ultimately, the Angular CDK Overlay service provides you with the flexibility to choose the interaction pattern that best fits your user experience goals. By understanding the trade-offs between outside pointer events and backdrops, you can craft overlays that are both functional and intuitive. Experiment with both approaches and carefully consider how your users will interact with your application to make the most informed decision.