Modal
Dialog overlay with focus management, header/body/footer projection, backdrop policy, and Escape handling.
- Selector
- ui-modal
- Package
- @ngnova/ui/modal
Import
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.
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.
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.
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.
| Name | Type | Default | Description |
|---|---|---|---|
open | boolean | false | Controls dialog visibility. |
closeOnBackdrop | boolean | true | Closes when the backdrop is clicked. |
closeOnEscape | boolean | true | Closes when Escape is pressed. |
size | 'sm' | 'md' | 'lg' | 'xl' | 'md' | Maximum dialog width. |
titleId | string | generated | ID used by aria-labelledby. |
descriptionId | string | '' | Optional ID used by aria-describedby. |
ariaLabel | string | '' | Accessible dialog label for headerless dialogs. |
closeAriaLabel | string | 'Close dialog' | Localized accessible label for the close action. |
initialFocus | string | '' | Optional CSS selector for the element focused when the dialog opens. |
restoreFocus | boolean | true | 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.
| Name | Type | Description |
|---|---|---|
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.