Component v1.1.0 Overlays

Modal

Dialog overlay with focus management, header/body/footer projection, backdrop policy, and Escape handling.

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

Import

Standalone Tailwind v4
import { UiModalComponent } from '@ngnova/ui/modal';

Usage & variants

Live examples use the public ui-modal API, paired with the exact snippet a product team would paste into an Angular app.

API Reference

Publish confirmation

Dialog overlay with focus management, header/body/footer projection, backdrop policy, and Escape handling.

Escape, backdrop policy, and focus restore are documented below.

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 confirmations, focused forms, destructive decisions, or short workflows that must interrupt the current page.

Watch for

Use ariaLabel for headerless dialogs.

Product recipes

Apply Modal in distinct, copyable product scenarios—not just an isolated component state.

Publish confirmation

Use two-way open binding, a description ID, and explicit dismissal policy.

Angular template ui-modal-recipe.example.html
1
2
3
4
5
6
7
8
9
10
11
12
13
<ui-modal
  [(open)]="publishOpen"
  size="lg"
  descriptionId="publish-description"
  [closeOnBackdrop]="false"
>
  <span uiModalHeader>Publish package</span>
  <p id="publish-description">This publishes the package to npm.</p>
  <div uiModalFooter>
    <ui-button variant="outline" (click)="publishOpen = false">Cancel</ui-button>
    <ui-button (pressed)="publish()">Publish</ui-button>
  </div>
</ui-modal>

Headerless destructive dialog

Use ariaLabel when no visible header labels the dialog.

Angular template ui-modal-recipe.example.html
1
2
3
4
5
6
7
8
9
10
11
12
<ui-modal
  [(open)]="deleteOpen"
  ariaLabel="Delete package confirmation"
  size="sm"
  [closeOnEscape]="false"
>
  <p>This action cannot be undone.</p>
  <div uiModalFooter>
    <ui-button variant="outline" (click)="deleteOpen = false">Keep package</ui-button>
    <ui-button variant="danger" (click)="deletePackage()">Delete</ui-button>
  </div>
</ui-modal>

API Reference

Inputs and outputs are semver-sensitive public API. Keep examples aligned with this table.

Inputs

open false
boolean

Controls dialog visibility.

closeOnBackdrop true
boolean

Closes when the backdrop is clicked.

closeOnEscape true
boolean

Closes when Escape is pressed.

size 'md'
'sm' | 'md' | 'lg' | 'xl'

Maximum dialog width.

titleId generated
string

ID used by aria-labelledby.

descriptionId ''
string

Optional ID used by aria-describedby.

ariaLabel ''
string

Accessible dialog label for headerless dialogs.

closeAriaLabel 'Close dialog'
string

Localized accessible label for the close action.

initialFocus ''
string

Optional CSS selector for the element focused when the dialog opens.

restoreFocus true
boolean

Restores focus to the previously focused element after close.

Outputs

openChange OutputEmitterRef<boolean>

Supports two-way open binding.

opened OutputEmitterRef<void>

Emits when the dialog opens.

closed OutputEmitterRef<void>

Emits after the dialog closes.

backdropClick OutputEmitterRef<MouseEvent>

Emits when the backdrop is clicked.

escapeKeyDown OutputEmitterRef<KeyboardEvent>

Emits when Escape closes the dialog.

Accessibility

  • Uses role="dialog" and aria-modal="true".
  • Supports aria-labelledby or ariaLabel and optional aria-describedby.
  • Moves focus into the dialog, traps Tab navigation, and restores the trigger by default.

Keyboard behavior

  • Escape closes when closeOnEscape is true.
  • Tab is trapped inside the dialog while open.

Testing guidance

  • Assert Escape, backdrop, focus trap, and focus restore behavior.