From f6a9b1ade76c06fd01201ebf0469feeef2e18eba Mon Sep 17 00:00:00 2001
From: Kristiyan Kostadinov <crisbeto@users.noreply.github.com>
Date: Fri, 27 Oct 2017 19:22:20 +0200
Subject: [PATCH] docs(dialog): add note about focus trapping (#7945)

Adds a note about the dialog's focus trapping behavior to the docs.

Fixes #7935.
---
 src/lib/dialog/dialog.md | 14 ++++++++++----
 1 file changed, 10 insertions(+), 4 deletions(-)

diff --git a/src/lib/dialog/dialog.md b/src/lib/dialog/dialog.md
index c20447c35b5..e817549982d 100644
--- a/src/lib/dialog/dialog.md
+++ b/src/lib/dialog/dialog.md
@@ -1,9 +1,9 @@
-The `MatDialog` service can be used to open modal dialogs with Material Design styling and 
+The `MatDialog` service can be used to open modal dialogs with Material Design styling and
 animations.
 
 <!-- example(dialog-overview) -->
 
-A dialog is opened by calling the `open` method with a component to be loaded and an optional 
+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`:
 
 ```ts
@@ -26,13 +26,13 @@ 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` promise. 
+value is forwarded as the result of the `afterClosed` promise.
 
 ```ts
 @Component({/* ... */})
 export class YourDialog {
   constructor(public dialogRef: MatDialogRef<YourDialog>) { }
-  
+
   closeDialog() {
     this.dialogRef.close('Pizza!');
   }
@@ -135,6 +135,12 @@ The `aria-label`, `aria-labelledby`, and `aria-describedby` attributes can all b
 dialog element via the `MatDialogConfig` as well. Each dialog should typically have a label
 set via `aria-label` or `aria-labelledby`.
 
+When a dialog is opened, it will move focus to the first focusable element that it can find. In
+order to prevent users from tabbing into elements in the background, the Material dialog uses
+a [focus trap](https://material.angular.io/cdk/a11y/overview#focustrap) to contain focus
+within itself. Once a dialog is closed, it will return focus to the element that was focused
+before the dialog was opened.
+
 #### Focus management
 By default, the first tabbable element within the dialog will receive focus upon open.