dialog.md

The Dialog service can be used to open unstyled modal dialogs and to build your own dialog services.

Initial setup

The CDK dialogs depend on a small set of structural styles to work correctly. If you're using Angular Material, these styles have been included together with the theme, otherwise if you're using the CDK on its own, you'll have to include the styles yourself. You can do so by importing the prebuilt styles in your global stylesheet:

@import '@angular/cdk/overlay-prebuilt.css';

Alternatively, you can include the styles using the cdk.overlay mixin in your Sass file. You can import the mixin as follows:

@use '@angular/cdk' as cdk;

@include cdk.overlay();

You can open a dialog by calling the open method either with a component or with a TemplateRef representing the dialog content. The method additionally accepts an optional configuration object. The open method returns a DialogRef instance:

const dialogRef = dialog.open(UserProfileComponent, {
  height: '400px',
  width: '600px',
  panelClass: 'my-dialog',
});

The DialogRef provides a reference to the opened dialog. You can use the DialogRef to close the dialog, subscribe to dialog events, and modify dialog state. All Observable instances on the DialogRef complete when the dialog closes.

dialogRef.closed.subscribe(result => {
  console.log(`Dialog result: ${result}`); // Pizza!
});

dialogRef.close('Pizza!');

Components created via Dialog can inject DialogRef and use it to close the dialog in which they are contained. When closing, an optional result value can be provided. This result value is forwarded as the result of the closed Observable.

import {inject} from '@angular/core';

@Component({/* ... */})
export class YourDialog {
  dialogRef = inject<DialogRef<string>>(DialogRef);

  closeDialog() {
    this.dialogRef.close('Pizza!');
  }
}

Dialog styling

The Dialog service includes an intentionally limited set of structural styles. You can customize the dialog's appearance using one of the following approaches.

panelClass option

The panelClass property of DialogConfig allows you to apply one or more CSS classes to the overlay element that contains the custom dialog content. Any styles targeting these CSS classes must be global styles.

Styling the dialog component

You can use the styles or styleUrls of a custom component to style the dialog content:

// MyDialog is rendered via `dialog.open(MyDialog)`
@Component({
  selector: 'my-dialog',
  styles: [`
    :host {
      display: block;
      background: #fff;
      border-radius: 8px;
      padding: 16px;
    }
  `]
})
class MyDialog {}

Providing a custom dialog container

If you want more control over the dialog's behavior and styling, you can provide your own dialog container component using the container option in DialogConfig. This approach requires more code up-front, but it allows you to customize the DOM structure and behavior of the container around the dialog content. Custom container components can optionally extend CdkDialogContainer to inherit standard behaviors, such as accessible focus management.

import {CdkDialogContainer} from '@angular/cdk/dialog';

@Component({
  selector: 'my-dialog-container',
  styles: [`
    :host {
      display: block;
      background: #fff;
      border-radius: 8px;
      padding: 16px;
    }
  `]
})
class MyDialogContainer extends CdkDialogContainer {}

Specifying global configuration defaults

Default dialog options can be specified by providing an instance of DialogConfig for DEFAULT_DIALOG_CONFIG in your app config.

bootstrapApplication(MyApp, {
  providers: [
    {provide: DEFAULT_DIALOG_CONFIG, useValue: {hasBackdrop: false}}
  ]
});

Sharing data with the Dialog component.

You can use the data option to pass information to the dialog component.

const dialogRef = dialog.open(YourDialog, {
  data: {name: 'frodo'},
});

Access the data in your dialog component with the DIALOG_DATA injection token:

import {Component, inject} from '@angular/core';
import {DIALOG_DATA} from '@angular/cdk/dialog';

@Component({
  selector: 'your-dialog',
  template: 'passed in {{ data.name }}',
})
export class YourDialog {
  data = inject<{name: string}>(DIALOG_DATA);
}

If you're using a TemplateRef for your dialog content, the data is available in the template:

<ng-template let-data>
  Hello, {{data.name}}
</ng-template>

If you're using a TemplateRef and need to access the DialogRef, you can use the following:

<ng-template let-data let-dialogRef="dialogRef">
    Hello, {{data.name}}
</ng-template>

Accessibility

Dialog creates modal dialogs that implement the ARIA role="dialog" pattern by default. You can change the dialog's role to alertdialog via the DialogConfig.

You should provide an accessible label to this root dialog element by setting the ariaLabel or ariaLabelledBy properties of DialogConfig. You can additionally specify a description element ID via the ariaDescribedBy property of DialogConfig.

Keyboard interaction

By default, the escape key closes Dialog. While you can disable this behavior via the disableClose property of DialogConfig, doing this breaks the expected interaction pattern for the ARIA role="dialog" pattern.

Focus management

When opened, Dialog traps browser focus such that it cannot escape the root role="dialog" element. By default, the first tabbable element in the dialog receives focus. You can customize which element receives focus with the autoFocus property of DialogConfig, which supports the following values.

Value	Behavior
first-tabbable	Focus the first tabbable element. This is the default setting.
first-header	Focus the first header element (role="heading", h1 through h6)
dialog	Focus the root role="dialog" element.
Any CSS selector	Focus the first element matching the given selector.

While the default setting applies the best behavior for most applications, special cases may benefit from these alternatives. Always test your application to verify the behavior that works best for your users.

Focus restoration

When closed, Dialog restores focus to the element that previously held focus when the dialog opened by default. You can customize the focus restoration behavior using the restoreFocus property of DialogConfig. It supports the following values.

Value type	Behavior
boolean	When true, focus will be restored to the previously-focused element, otherwise focus won't be restored at all.
string	Value is treated as a CSS selector. Focus will be restored to the element matching the selector.
HTMLElement	Specific element that focus should be restored to.