Overview for dialog
The MatDialog
service can be used to open modal dialogs with Material Design styling and
animations.
A dialog is opened by calling the open
method with a component to be loaded and an optional
config object. The open
method will return an instance of MatDialogRef
:
let dialogRef = dialog.open(UserProfileComponent, {
height: '400px',
width: '600px',
});
The MatDialogRef
provides a handle on the opened dialog. It can be used to close the dialog and to
receive notifications when the dialog has been closed. Any notification Observables will complete when the dialog closes.
dialogRef.afterClosed().subscribe(result => {
console.log(`Dialog result: ${result}`); // Pizza!
});
dialogRef.close('Pizza!');
Components created via MatDialog
can inject MatDialogRef
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 afterClosed
Observable.
@Component({/* ... */})
export class YourDialog {
constructor(public dialogRef: MatDialogRef<YourDialog>) { }
closeDialog() {
this.dialogRef.close('Pizza!');
}
}
Specifying global configuration defaults
Default dialog options can be specified by providing an instance of MatDialogConfig
for
MAT_DIALOG_DEFAULT_OPTIONS in your application's root module.
@NgModule({
providers: [
{provide: MAT_DIALOG_DEFAULT_OPTIONS, useValue: {hasBackdrop: false}}
]
})
Sharing data with the Dialog component.
If you want to share data with your dialog, you can use the data
option to pass information to the dialog component.
let dialogRef = dialog.open(YourDialog, {
data: { name: 'austin' },
});
To access the data in your dialog component, you have to use the MAT_DIALOG_DATA injection token:
import {Component, Inject} from '@angular/core';
import {MAT_DIALOG_DATA} from '@angular/material/dialog';
@Component({
selector: 'your-dialog',
template: 'passed in {{ data.name }}',
})
export class YourDialog {
constructor(@Inject(MAT_DIALOG_DATA) public data: {name: string}) { }
}
Note that if you're using a template dialog (one that was opened with a TemplateRef
), the data
will be available implicitly in the template:
<ng-template let-data>
Hello, {{data.name}}
</ng-template>
Dialog content
Several directives are available to make it easier to structure your dialog content:
Name | Description |
---|---|
mat-dialog-title |
[Attr] Dialog title, applied to a heading element (e.g., <h1> , <h2> ) |
<mat-dialog-content> |
Primary scrollable content of the dialog. |
<mat-dialog-actions> |
Container for action buttons at the bottom of the dialog. Button alignment can be controlled via the align attribute which can be set to end and center . |
mat-dialog-close |
[Attr] Added to a <button> , makes the button close the dialog with an optional result from the bound value. |
For example:
<h2 mat-dialog-title>Delete all elements?</h2>
<mat-dialog-content>This will delete all elements that are currently on this page and cannot be undone.</mat-dialog-content>
<mat-dialog-actions>
<button mat-button mat-dialog-close>Cancel</button>
<!-- The mat-dialog-close directive optionally accepts a value as a result for the dialog. -->
<button mat-button [mat-dialog-close]="true">Delete</button>
</mat-dialog-actions>
Once a dialog opens, the dialog will automatically focus the first tabbable element.
You can control which elements are tab stops with the tabindex
attribute
<button mat-button tabindex="-1">Not Tabbable</button>
Controlling the dialog animation
You can control the duration of the dialog's enter and exit animations using the
enterAnimationDuration
and exitAnimationDuration
options. If you want to disable the dialog's
animation completely, you can do so by setting the properties to 0ms
.
Accessibility
MatDialog
creates modal dialogs that implements the ARIA role="dialog"
pattern by default.
You can change the dialog's role to alertdialog
via MatDialogConfig
.
You should provide an accessible label to this root dialog element by setting the ariaLabel
or
ariaLabelledBy
properties of MatDialogConfig
. You can additionally specify a description element
ID via the ariaDescribedBy
property of MatDialogConfig
.
Keyboard interaction
By default, the escape key closes MatDialog
. While you can disable this behavior via
the disableClose
property of MatDialogConfig
, doing this breaks the expected interaction
pattern for the ARIA role="dialog"
pattern.
Focus management
When opened, MatDialog
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
MatDialogConfig
, 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, MatDialog
restores focus to the element that previously held focus when the
dialog opened. However, if that previously focused element no longer exists, you must
add additional handling to return focus to an element that makes sense for the user's workflow.
Opening a dialog from a menu is one common pattern that causes this situation. The menu
closes upon clicking an item, thus the focused menu item is no longer in the DOM when the bottom
sheet attempts to restore focus.
You can add handling for this situation with the afterClosed()
observable from MatDialogRef
.
const dialogRef = this.dialog.open(DialogFromMenuExampleDialog, {restoreFocus: false});
// Manually restore focus to the menu trigger since the element that
// opens the dialog won't be in the DOM any more when the dialog closes.
dialogRef.afterClosed().subscribe(() => this.menuTrigger().focus());