From de81baf8b1c3904987d86ff04a628aad3fbac2ad Mon Sep 17 00:00:00 2001 From: shivdev277 Date: Thu, 5 Feb 2026 18:25:44 +0530 Subject: [PATCH 1/4] docs(cdk/overlay): document native popover API usage - Add new section explaining the usePopover option - Include code examples for basic and advanced usage - List benefits of using the native Popover API - Add browser compatibility note Closes # --- src/cdk/overlay/overlay.md | 40 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/src/cdk/overlay/overlay.md b/src/cdk/overlay/overlay.md index 8030aaa6b856..c85c1e8ba578 100644 --- a/src/cdk/overlay/overlay.md +++ b/src/cdk/overlay/overlay.md @@ -87,6 +87,46 @@ strategy will typically inject `ScrollDispatcher` (from `@angular/cdk/scrolling` of when scrolling takes place. See the documentation for `ScrollDispatcher` for more information on how scroll events are detected and dispatched. +#### Using the native Popover API +As of Angular v21, the CDK overlay supports rendering overlays as native popover elements instead +of using the traditional overlay container. This uses the browser's native [Popover API](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API), +which provides improved accessibility, automatic focus management, and better handling of scrolling +and positioning. + +To enable the popover behavior, set the `usePopover` option to `true` when creating an overlay: + +```ts +const overlayRef = overlay.create({ + positionStrategy: this.overlay.position() + .flexibleConnectedTo(trigger) + .withPositions(positions), + usePopover: true, +}); +``` + +When using `FlexibleConnectedPositionStrategy` with popovers, you can also specify the popover +insertion point: + +```ts +const overlayRef = overlay.create({ + positionStrategy: this.overlay.position() + .flexibleConnectedTo(trigger) + .withPositions(positions) + .withPopoverInsertionPoint(triggerElement), + usePopover: 'auto', // Can also use 'auto', 'manual' +}); +``` + +**Benefits of using the native Popover API:** +- Better accessibility with automatic focus management +- Automatic dismissal on outside click (for auto popovers) +- Improved performance with less CSS in the critical path +- Native browser support for popover stacking +- Better integration with screen readers + +**Note:** The popover API is not supported on older browsers. Always provide a fallback or test +browser compatibility before using this feature in production. + ### The overlay container The `OverlayContainer` provides a handle to the container element in which all individual overlay elements are rendered. By default, the overlay container is appended directly to the document body From b130ddc04a0a8e000982a691210c5e7f93558ea4 Mon Sep 17 00:00:00 2001 From: shivdev277 Date: Thu, 5 Feb 2026 18:31:27 +0530 Subject: [PATCH 2/4] docs(cdk/overlay): document native popover API usage - Add new section explaining the usePopover configuration option - Include code examples for basic and advanced usage patterns - List benefits of using the native Popover API - Add browser compatibility notes for older browsers --- src/cdk/overlay/overlay.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/cdk/overlay/overlay.md b/src/cdk/overlay/overlay.md index c85c1e8ba578..6b5908bcddfc 100644 --- a/src/cdk/overlay/overlay.md +++ b/src/cdk/overlay/overlay.md @@ -1,4 +1,4 @@ -The `overlay` package provides a way to open floating panels on the screen. +The `overlay` package provides a way to open floating panels on the screen. ### Initial setup The CDK overlays depend on a small set of structural styles to work correctly. If you're using From 96ef28e2ab21fef09a27dc59bf6fb3887648fbee Mon Sep 17 00:00:00 2001 From: shivdev277 Date: Sat, 7 Feb 2026 14:41:21 +0530 Subject: [PATCH 3/4] chore: retrigger CLA check From 145c0a5394152cefa4c424d7121d18902be87fc2 Mon Sep 17 00:00:00 2001 From: shivdev277 Date: Sat, 7 Feb 2026 15:24:28 +0530 Subject: [PATCH 4/4] ci(cla): retrigger CLA check