Skip to content

Commit f6a9b1a

Browse files
crisbetommalerba
authored andcommitted
docs(dialog): add note about focus trapping (#7945)
Adds a note about the dialog's focus trapping behavior to the docs. Fixes #7935.
1 parent 305dccf commit f6a9b1a

File tree

1 file changed

+10
-4
lines changed

1 file changed

+10
-4
lines changed

src/lib/dialog/dialog.md

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
1-
The `MatDialog` service can be used to open modal dialogs with Material Design styling and
1+
The `MatDialog` service can be used to open modal dialogs with Material Design styling and
22
animations.
33

44
<!-- example(dialog-overview) -->
55

6-
A dialog is opened by calling the `open` method with a component to be loaded and an optional
6+
A dialog is opened by calling the `open` method with a component to be loaded and an optional
77
config object. The `open` method will return an instance of `MatDialogRef`:
88

99
```ts
@@ -26,13 +26,13 @@ dialogRef.close('Pizza!');
2626

2727
Components created via `MatDialog` can _inject_ `MatDialogRef` and use it to close the dialog
2828
in which they are contained. When closing, an optional result value can be provided. This result
29-
value is forwarded as the result of the `afterClosed` promise.
29+
value is forwarded as the result of the `afterClosed` promise.
3030

3131
```ts
3232
@Component({/* ... */})
3333
export class YourDialog {
3434
constructor(public dialogRef: MatDialogRef<YourDialog>) { }
35-
35+
3636
closeDialog() {
3737
this.dialogRef.close('Pizza!');
3838
}
@@ -135,6 +135,12 @@ The `aria-label`, `aria-labelledby`, and `aria-describedby` attributes can all b
135135
dialog element via the `MatDialogConfig` as well. Each dialog should typically have a label
136136
set via `aria-label` or `aria-labelledby`.
137137

138+
When a dialog is opened, it will move focus to the first focusable element that it can find. In
139+
order to prevent users from tabbing into elements in the background, the Material dialog uses
140+
a [focus trap](https://material.angular.io/cdk/a11y/overview#focustrap) to contain focus
141+
within itself. Once a dialog is closed, it will return focus to the element that was focused
142+
before the dialog was opened.
143+
138144
#### Focus management
139145
By default, the first tabbable element within the dialog will receive focus upon open.
140146

0 commit comments

Comments
 (0)