Reproduction link
Steps to reproduce
Potential positioning issues with FlexibleConnectedPositionStrategy when CDK usePopover is enabled (Top Layer conflict)
Description
With the recent updates in Angular CDK (v19/v21), the createOverlayRef now defaults (or fallback) usePopover to true when the browser supports the showPopover API. This results in the overlay host being assigned the popover="manual" attribute, moving the element into the browser's Top Layer.
While this solves many z-index and overflow: hidden issues, it introduces a discrepancy in how FlexibleConnectedPositionStrategy calculates the available space.
Root Cause Analysis
Top Layer Nature: Once an element enters the Top Layer via the Popover API, it is removed from the normal document flow. It is no longer constrained by the parent's overflow, transform, or z-index.
CDK Calculation Logic:
In FlexibleConnectedPositionStrategy._getContainerRect(), the CDK still relies on this._overlayContainer.getContainerElement().getBoundingClientRect() to determine the bounding box/available space for the overlay.
The Conflict
The overlayContainer element is typically a div inside the body.
When using the Popover API, the element's coordinate system and clipping behavior should technically be relative to the Viewport (as it is in the Top Layer), but the CDK logic might still be applying constraints based on the overlayContainer rect.
If the overlayContainer has specific styles or if the viewport calculation logic doesn't account for the "escape" from the DOM tree, it leads to incorrect positioning or unnecessary shifting/flipping.
Steps to Reproduce
Use Angular CDK v19/v21 in a browser supporting showPopover.
Create a component using NzOverlay or any component relying on FlexibleConnectedPositionStrategy.
Observe the positioning behavior when the parent container has complex layouts or when the overlayContainer is not matching the full viewport.
Expected Behavior:
The FlexibleConnectedPositionStrategy should detect if usePopover is active and adjust its _getContainerRect() or viewport boundary detection to reflect that the element is now in the Top Layer, bypassing traditional container constraints.
Possible Impact on NG-ZORRO:
Since NG-ZORRO components (Select, DatePicker, Popover, Tooltip) heavily rely on CDK positioning, users might see:
Overlays being clipped incorrectly.
"Flip" behavior triggering when there is actually enough space in the Top Layer.
Misalignment in specific edge cases where the container rect differs from the visual viewport.
Suggested Mitigation:
We might need to:
Explicitly check if the overlay is using the Popover API.
If yes, ensure the boundaryRect defaults to the viewport rather than the overlayContainer's bounding box.
Or, provide a way to toggle usePopover: false in NzConfigService until the CDK's internal strategy fully matures for Top Layer calculations.
What is expected?
fix
What is actually happening?
closed overlay config
| Environment |
Info |
| ng-zorro-antd |
21.2.1 |
| Browser |
chromium（chrome、edge...） |
Reproduction link
Steps to reproduce
Potential positioning issues with FlexibleConnectedPositionStrategy when CDK
usePopoveris enabled (Top Layer conflict)Description
With the recent updates in Angular CDK (v19/v21), the createOverlayRef now defaults (or fallback) usePopover to true when the browser supports the showPopover API. This results in the overlay host being assigned the popover="manual" attribute, moving the element into the browser's Top Layer.
While this solves many z-index and overflow: hidden issues, it introduces a discrepancy in how FlexibleConnectedPositionStrategy calculates the available space.
Root Cause Analysis
Top Layer Nature: Once an element enters the Top Layer via the Popover API, it is removed from the normal document flow. It is no longer constrained by the parent's overflow, transform, or z-index.
CDK Calculation Logic:
In
FlexibleConnectedPositionStrategy._getContainerRect(), the CDK still relies onthis._overlayContainer.getContainerElement().getBoundingClientRect()to determine the bounding box/available space for the overlay.The Conflict
The overlayContainer element is typically a div inside the body.
When using the Popover API, the element's coordinate system and clipping behavior should technically be relative to the Viewport (as it is in the Top Layer), but the CDK logic might still be applying constraints based on the overlayContainer rect.
If the overlayContainer has specific styles or if the viewport calculation logic doesn't account for the "escape" from the DOM tree, it leads to incorrect positioning or unnecessary shifting/flipping.
Steps to Reproduce
Use Angular CDK v19/v21 in a browser supporting showPopover.
Create a component using NzOverlay or any component relying on FlexibleConnectedPositionStrategy.
Observe the positioning behavior when the parent container has complex layouts or when the overlayContainer is not matching the full viewport.
Expected Behavior:
The FlexibleConnectedPositionStrategy should detect if usePopover is active and adjust its _getContainerRect() or viewport boundary detection to reflect that the element is now in the Top Layer, bypassing traditional container constraints.
Possible Impact on NG-ZORRO:
Since NG-ZORRO components (Select, DatePicker, Popover, Tooltip) heavily rely on CDK positioning, users might see:
Overlays being clipped incorrectly.
"Flip" behavior triggering when there is actually enough space in the Top Layer.
Misalignment in specific edge cases where the container rect differs from the visual viewport.
Suggested Mitigation:
We might need to:
Explicitly check if the overlay is using the Popover API.
If yes, ensure the boundaryRect defaults to the viewport rather than the overlayContainer's bounding box.
Or, provide a way to toggle usePopover: false in NzConfigService until the CDK's internal strategy fully matures for Top Layer calculations.
What is expected?
fix
What is actually happening?
closed overlay config