In Angular CDK 22, how does an overlay escape a scrolling grid's overflow clipping, and what do usePopover, withPopoverLocation and the OverlayContainer change?
answer
- render outside the clipping subtree
- a container div under body
- manual popover where supported
- global, inline or a parent
- opt out with a DI token
basics
~20 sA CDK 22 overlay's host becomes a manual popover drawn in the browser's top layer, so ancestor overflow cannot clip it; without popover support it sits in the OverlayContainer under body. withPopoverLocation only moves the popover in the DOM.
solid answer
~40 s`createOverlayRef` creates a host element holding the pane. Where the Popover API exists and `usePopover` is not turned off, the host gets `popover="manual"` and is shown with `showPopover()`, so the browser renders it in the top layer, above any `overflow: hidden` or `z-index` of the grid. Without popover support, or when you opt out, the host goes into the `OverlayContainer`: one fixed-position `div.cdk-overlay-container` appended to `<body>` with a z-index of 1000, which escapes clipping by living outside the grid's subtree. In popover mode, `withPopoverLocation('global' | 'inline' | {type: 'parent', element})` or `cdkConnectedOverlayUsePopover` only decides where the host sits in the DOM; `'inline'` puts it right after the trigger, keeping DOM order close to visual order. `OVERLAY_DEFAULT_CONFIG` with `{usePopover: false}` opts out app-wide.
go deeper
Recall that CDK overlays render outside the component's DOM, either as a native popover or inside a container under body, which is why parent overflow cannot cut them off.
Explain how createOverlayRef decides on popover mode, what the overlay container is, and what each popover location value does.
Diagnose clipping and stacking bugs by checking which path an overlay took, fix z-index fights in the fallback path, choose inline placement for reading order, and handle full-screen grids with the full-screen container.
Decide whether the product keeps popover mode or opts out, weighing top-layer reliability against tests and styles that assume the overlay container, and record it as one app-level provider.
## The problem the overlay solves A spreadsheet-like grid usually scrolls inside its own container with `overflow: auto`, often inside cards that set `overflow: hidden`. An editor or filter panel rendered as a child of a cell would be clipped by those ancestors. The Angular CDK overlay avoids this by never rendering the panel inside the grid's subtree. How it does that depends on the version and the browser. ## Path 1: native popover (the default in CDK 22) `createOverlayRef(injector, config)` builds two elements: a **host** and, inside it, the **pane** that receives the portal. It then decides `usePopover`: 1. if the document has no `showPopover` support, it is forced to false; 2. otherwise the config's `usePopover` wins; 3. otherwise `OVERLAY_DEFAULT_CONFIG.usePopover`, and if that is not provided, `true`. In popover mode the host gets `popover="manual"` and the class `cdk-overlay-popover`, and attaching calls `showPopover()`. A shown popover is drawn in the browser's **top layer**, so no ancestor's `overflow`, `z-index` or stacking context can clip it or cover it. The backdrop, when requested, is placed inside the popover so it stays beneath the pane. ## Path 2: the OverlayContainer Without popover support, or after opting out, the host is appended to the **`OverlayContainer`**: a single `div` with the class `cdk-overlay-container`, created lazily and appended to `document.body`. Its CSS is `position: fixed` with `z-index: 1000` by default (the CDK Sass variable `$overlay-container-z-index`). Being a child of `<body>` puts it outside every clipping ancestor of the grid; the high z-index puts it above ordinary page content. In popover mode the container is still the default insertion point. | | Native popover | OverlayContainer only | |---|---|---| | Escapes ancestor `overflow` | yes, top layer | yes, lives under body | | Beats page `z-index` | yes, top layer | only up to its z-index of 1000 | | DOM location | container by default, or chosen | always the container | | Turned on by | browser support plus `usePopover` | absence of either | ## Choosing where the popover sits In popover mode the DOM location no longer affects clipping, so the CDK lets you choose it for reading order and focus order. `FlexibleConnectedPositionStrategy.withPopoverLocation()` and the directive's `cdkConnectedOverlayUsePopover` input accept: - `'global'`: the default, inside the overlay container; - `'inline'`: immediately after the trigger element; - `{type: 'parent', element}`: as a child of an element you name. The guide recommends `'inline'` for accessibility, because a screen reader walking the DOM meets the panel right after its trigger. Angular Material's select, for instance, places its panel inline unless popovers are disabled app-wide. Location applies only when the overlay really is a popover; in the fallback path the container is used regardless. ## Telling which path an overlay took In the browser's element inspector: - a host with the `popover` attribute and the class `cdk-overlay-popover` is in popover mode; its DOM parent shows the chosen location; - a host without it, inside `.cdk-overlay-container`, is on the fallback path, and z-index rules apply; - the pane inside either host carries the class `cdk-overlay-pane` and any `panelClass` you set. Knowing the path tells you whether a stacking bug is even possible: in popover mode it is not, in the fallback path it is the first suspect. ## Opting out and special containers ```ts import {OVERLAY_DEFAULT_CONFIG} from '@angular/cdk/overlay'; bootstrapApplication(App, { providers: [{provide: OVERLAY_DEFAULT_CONFIG, useValue: {usePopover: false}}], }); ``` - `OverlayConfig.usePopover` overrides the token for a single overlay. - Opting out is a reasonable choice when other code relies on overlays being in `.cdk-overlay-container`, such as global styles or end-to-end selectors. - If the grid offers a full-screen mode through the Fullscreen API, only the full-screen element and its children are shown. Providing `FullscreenOverlayContainer` in place of `OverlayContainer` moves the container into the full-screen element on each change. ## Lifecycle and DOM hygiene - `detach()` removes the host from the DOM once the pane is empty, to avoid scroll jank, and puts it back on the next `attach()`. - `dispose()` removes the host for good and completes the overlay's streams. - Forgetting `dispose()` when the opening component is destroyed leaves the ref, its strategies and its subscriptions alive, even if nothing is visible.
- With popovers on, why might you still choose 'inline' over the default global location for the grid's filter panel?Clipping no longer depends on DOM location, so the choice is about order. Inline places the host right after the header button, so keyboard tab order and screen-reader reading order meet the panel next to its trigger instead of at the end of `<body>`. The panel still renders in the top layer.
- In the fallback path, a sticky toolbar with z-index 2000 covers the editor overlay. What is going on?Without popovers the overlay container is a fixed element under body with a default z-index of 1000, so a page element in the same stacking context with a higher z-index paints over it. Lower the toolbar or raise the container: the auto-loaded CDK styles put that z-index in a `cdk-overlay` cascade layer, so a plain global rule on `.cdk-overlay-container` overrides it. In popover mode the top layer avoids the conflict.
- Overlays escape clipping by giving the pane a very high z-index in place.
- withPopoverLocation('inline') makes the panel subject to the grid's overflow.
- OVERLAY_DEFAULT_CONFIG is how you turn popovers on.
- The overlay container is created inside the component that opens the overlay.
- Detached overlays keep their host in the DOM until the page reloads.
Assumes Angular CDK 22: createOverlayRef uses native popovers by default when the browser supports them, and the OVERLAY_DEFAULT_CONFIG opt-out token arrived in 21.0.0.