Component v1.1.0 Overlays

Advanced Overlay

Optional Angular CDK connected-overlay primitive with fallback placement, scroll policy, dismissal control, focus management, and typed lifecycle events.

API Stable 2.1 WCAG notes Ready Dark mode
Selector
ui-overlay
Package
@ngnova/ui/overlay

Import

Standalone Tailwind v4
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.

API Reference

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.

Angular template ui-overlay-recipe.example.html
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.

Angular template ui-overlay-recipe.example.html
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.

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.

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.