Advanced Overlay
Optional Angular CDK connected-overlay primitive with fallback placement, scroll policy, dismissal control, focus management, and typed lifecycle events.
- Selector
- ui-overlay
- Package
- @ngnova/ui/overlay
Import
import { UiOverlayComponent, UiOverlayTriggerDirective, UiOverlayContentDirective } from '@ngnova/ui/overlay';Usage & variants
Live examples use the public ui-overlay API, paired with the exact snippet a product team would paste into an Angular app.
Connected release actions
Optional Angular CDK connected-overlay primitive with fallback placement, scroll policy, dismissal control, focus management, and typed lifecycle events.
Production guidance
Use these notes to decide when the component belongs in a product workflow and what to verify before shipping.
When to use
Use for custom pickers, inspectors, contextual panels, and application-specific floating surfaces.
Watch for
Placement order is meaningful; an empty list falls back to bottom, top, right, and left.
Product recipes
Apply Advanced Overlay in distinct, copyable product scenarios—not just an isolated component state.
Connected release panel
Ordered placements and repositioning keep the panel visible without embedding CDK behavior in basic components.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
<ui-overlay
[open]="open()"
(openChange)="open.set($event)"
[placements]="['bottom', 'top']"
alignment="center"
[gap]="8"
scrollStrategy="reposition"
initialFocus="first"
ariaLabel="Release actions"
>
<button uiOverlayTrigger type="button">Open actions</button>
<div uiOverlayContent>
<button type="button">Run release check</button>
</div>
</ui-overlay>Notification inspector
Anchor a compact, interactive notification list to its trigger without introducing a modal task.
1 2 3 4 5 6 7
<ui-overlay placement="bottom-end">
<button uiOverlayTrigger uiButton variant="ghost">Notifications</button>
<section uiOverlayContent aria-label="Recent notifications" class="w-80 p-4">
<h3>Recent notifications</h3>
<a href="/releases/42">Release 4.2 is ready to review</a>
</section>
</ui-overlay>API Reference
Inputs and outputs are semver-sensitive public API. Keep examples aligned with this table.
Inputs
open false boolean Controlled attachment state.
disabled false boolean Prevents trigger pointer and keyboard requests.
placements ['bottom', 'top', 'right', 'left'] readonly UiOverlayPlacement[] Ordered placement candidates for collision fallback.
alignment 'start' UiOverlayAlignment Start, center, or end cross-axis alignment.
gap 8 number Non-negative main-axis distance from the origin in pixels.
crossAxisOffset 0 number Signed cross-axis adjustment in pixels.
viewportMargin 8 number Minimum viewport-edge distance in pixels.
scrollStrategy 'reposition' UiOverlayScrollStrategy Reposition, close, block, or no-op behavior during page scrolling.
role 'dialog' UiOverlayRole Semantic role for projected connected content.
ariaLabel '' string Accessible name for the overlay panel.
panelId 'ui-overlay-{id}' string Stable unique panel ID used by trigger relationships.
hasBackdrop false boolean Adds a CDK backdrop.
backdropClass 'cdk-overlay-transparent-backdrop' string Class applied to the optional CDK backdrop.
closeOnOutside true boolean Requests closure after an outside pointer event.
closeOnBackdrop true boolean Requests closure after backdrop interaction.
closeOnEscape true boolean Requests closure after Escape.
matchTriggerWidth false boolean Matches the overlay pane width to its origin.
flexibleDimensions true boolean Allows CDK to constrain the panel to viewport dimensions.
growAfterOpen true boolean Allows the connected panel to grow after attachment.
push true boolean Pushes the panel on screen when no placement fully fits.
lockPosition false boolean Prevents placement switching after the first position.
disposeOnNavigation true boolean Disposes the CDK overlay on browser navigation.
initialFocus 'none' UiOverlayInitialFocus Moves focus to none, the panel, or its first focusable descendant.
restoreFocus true boolean Returns focus to the previously active element after detachment.
uiOverlayTrigger required directive Marks the projected interactive origin that requests controlled toggling.
uiOverlayContent required directive Marks projected content portaled into the connected CDK pane.
| Name | Type | Default | Description |
|---|---|---|---|
open | boolean | false | Controlled attachment state. |
disabled | boolean | false | Prevents trigger pointer and keyboard requests. |
placements | readonly UiOverlayPlacement[] | ['bottom', 'top', 'right', 'left'] | Ordered placement candidates for collision fallback. |
alignment | UiOverlayAlignment | 'start' | Start, center, or end cross-axis alignment. |
gap | number | 8 | Non-negative main-axis distance from the origin in pixels. |
crossAxisOffset | number | 0 | Signed cross-axis adjustment in pixels. |
viewportMargin | number | 8 | Minimum viewport-edge distance in pixels. |
scrollStrategy | UiOverlayScrollStrategy | 'reposition' | Reposition, close, block, or no-op behavior during page scrolling. |
role | UiOverlayRole | 'dialog' | Semantic role for projected connected content. |
ariaLabel | string | '' | Accessible name for the overlay panel. |
panelId | string | 'ui-overlay-{id}' | Stable unique panel ID used by trigger relationships. |
hasBackdrop | boolean | false | Adds a CDK backdrop. |
backdropClass | string | 'cdk-overlay-transparent-backdrop' | Class applied to the optional CDK backdrop. |
closeOnOutside | boolean | true | Requests closure after an outside pointer event. |
closeOnBackdrop | boolean | true | Requests closure after backdrop interaction. |
closeOnEscape | boolean | true | Requests closure after Escape. |
matchTriggerWidth | boolean | false | Matches the overlay pane width to its origin. |
flexibleDimensions | boolean | true | Allows CDK to constrain the panel to viewport dimensions. |
growAfterOpen | boolean | true | Allows the connected panel to grow after attachment. |
push | boolean | true | Pushes the panel on screen when no placement fully fits. |
lockPosition | boolean | false | Prevents placement switching after the first position. |
disposeOnNavigation | boolean | true | Disposes the CDK overlay on browser navigation. |
initialFocus | UiOverlayInitialFocus | 'none' | Moves focus to none, the panel, or its first focusable descendant. |
restoreFocus | boolean | true | Returns focus to the previously active element after detachment. |
uiOverlayTrigger | directive | required | Marks the projected interactive origin that requests controlled toggling. |
uiOverlayContent | directive | required | Marks projected content portaled into the connected CDK pane. |
Outputs
openChange OutputEmitterRef<boolean> Requests controlled attachment changes.
opened OutputEmitterRef<void> Emits after the CDK overlay attaches.
closed OutputEmitterRef<void> Emits after the CDK overlay detaches.
backdropClick OutputEmitterRef<MouseEvent> Emits the native backdrop event before dismissal policy.
outsideClick OutputEmitterRef<MouseEvent> Emits a click outside both origin and panel.
escapeKeyDown OutputEmitterRef<void> Emits Escape before dismissal policy.
positionChange OutputEmitterRef<UiOverlayPositionChange> Reports the resolved placement and requested alignment.
| Name | Type | Description |
|---|---|---|
openChange | OutputEmitterRef<boolean> | Requests controlled attachment changes. |
opened | OutputEmitterRef<void> | Emits after the CDK overlay attaches. |
closed | OutputEmitterRef<void> | Emits after the CDK overlay detaches. |
backdropClick | OutputEmitterRef<MouseEvent> | Emits the native backdrop event before dismissal policy. |
outsideClick | OutputEmitterRef<MouseEvent> | Emits a click outside both origin and panel. |
escapeKeyDown | OutputEmitterRef<void> | Emits Escape before dismissal policy. |
positionChange | OutputEmitterRef<UiOverlayPositionChange> | Reports the resolved placement and requested alignment. |
Accessibility
- The trigger receives aria-haspopup, aria-expanded, and aria-controls based on controlled state and the selected panel role.
- Consumers must choose a role that matches projected semantics and provide ariaLabel when content has no internal labelling relationship.
- Initial focus is opt-in; restoration returns users to the element active when the overlay attached.
Keyboard behavior
- Enter, Space, or Arrow Down requests opening from the trigger; native trigger behavior remains available.
- Escape always emits escapeKeyDown and follows closeOnEscape policy.
- Projected interactive content owns its internal keyboard model; use established Menu or Listbox components for those semantics.
Testing guidance
- Assert fallback position reporting, scroll strategy choice, controlled trigger state, outside/backdrop/Escape policy, focus entry/restore, navigation disposal, localization, and UiOverlayHarness toggling.