Dialog

A dialog is a floating window that can be used to display information or prompt the user for input.

Import

Import the Dialog primitives from ng-primitives/dialog.

import {
  NgpDialog,
  NgpDialogTitle,
  NgpDialogDescription,
  NgpDialogTrigger,
  NgpDialogOverlay,
} from 'ng-primitives/dialog';

Usage

Assemble the dialog directives in your template.

<button [ngpDialogTrigger]="dialog" ngpButton>Launch Dialog</button>

<ng-template #dialog let-close="close">
  <div ngpDialogOverlay>
    <div ngpDialog>
      <h1 ngpDialogTitle>Publish this article?</h1>
      <p ngpDialogDescription>
        Are you sure you want to publish this article? This action is irreversible.
      </p>
      <div class="dialog-footer">
        <button (click)="close()" ngpButton>Cancel</button>
        <button (click)="close()" ngpButton>Confirm</button>
      </div>
    </div>
  </div>
</ng-template>

Reusable Component

Create reusable components that uses the NgpDialog and NgpDialogTrigger directives.

Schematics

Generate a reusable dialog component using the Angular CLI.

ng g ng-primitives:primitive dialog

Options

• path: The path at which to create the component file.
• prefix: The prefix to apply to the generated component selector.
• component-suffix: The suffix to apply to the generated component class name.
• file-suffix: The suffix to apply to the generated component file name. Defaults to component.
• styles: How component styles should be generated. css (default) includes the full example styles; unstyled omits them entirely so you can style the component yourself.
• example-styles (deprecated): still supported for compatibility - true maps to styles: css, false maps to styles: unstyled.

Examples

Dismiss Guard

Use dismiss guards to prevent a dialog from closing when there are unsaved changes. The closeOnEscape and closeOnOutsideClick options accept a guard function that returns a boolean or a Promise<boolean>.

Dialog with external data

Data can be passed to the dialog using the NgpDialogManager.

Drawer

A drawer is a type of dialog that slides in from the side of the screen.

API Reference

The following directives are available to import from the ng-primitives/dialog package:

NgpDialog

NgpDialogTitle

NgpDialogDescription

NgpDialogTrigger

NgpDialogOverlay

NgpDialogManager

The NgpDialogManager can be used as an alternative to the NgpDialogTrigger directive for programmatically opening dialogs.

The manager provides methods to open, close, and query dialogs, and accepts a component or template reference to display.

NgpDialogRef

Reference returned by NgpDialogManager.open(). Provides methods to interact with the opened dialog.

Closes the dialog, optionally returning a result value. Observable that emits immediately when `close()` is called, before exit animations run. Observable that emits after exit animations have completed. The data passed to the dialog via `NgpDialogConfig.data`. The unique ID for the dialog. Whether the user is allowed to close the dialog. Whether the escape key is allowed to close the dialog, or a guard function. When a function is provided, it receives the keyboard event and should return a boolean or `Promise`. Whether clicking outside (on the overlay) is allowed to close the dialog, or a guard function. When a function is provided, it receives the target element and should return a boolean or `Promise`. Observable that emits keyboard events dispatched within the dialog. Observable that emits pointer events dispatched outside of the dialog. Updates the position of the dialog. Currently a no-op as dialogs are CSS-centered.

Global Configuration

You can configure the default options for all dialogs in your application by using the provideDialogConfig function in a providers array.

import { provideDialogConfig } from 'ng-primitives/dialog';

bootstrapApplication(AppComponent, {
  providers: [
    provideDialogConfig({
      container: '#app-root',
      role: 'dialog',
      modal: true,
    }),
  ],
});

By default dialogs render into document.body. The container option accepts an element or a selector, which is useful when the dialog must live inside a specific subtree - for example a micro-frontend root or an element carrying your theme class. It can be overridden per dialog through NgpDialogTrigger's ngpDialogTriggerContainer input, or through the container option passed to NgpDialogManager.open().

NgpDialogConfig

Accessibility

Adheres to the WAI-ARIA design pattern.

Keyboard Interactions

• Esc: Close the dialog.
• Tab: Navigate through focusable elements within the dialog.
• Shift + Tab: Navigate backwards through focusable elements within the dialog.