# Modal Dialog

The dialog component can be used to focus a user's attention on a single piece of content, without taking them to a new screen. Please use with caution; view our guidance for more details.

## Guidance

### Accessibility

#### Keyboard support

- `Enter` or `Space` to select the highlighted item.
- `Tab` to move the focus sequentially through the list of focusable items.
- `Shift + Tab` to move the focus sequentially through the list of focusable items in reversed order.

#### Focus Management

- When the modal is opened, the entire modal is the default focus state. Most screen readers will announce the entire dialog content.
- Focus is trapped within the modal and users can then navigate through the dialog actions with the keyboard.
- Escape will close the modal. To disable exiting when users press the Escape key, set the `escapeExits` prop to `false`
- When the modal closes, focus returns to the element that was focused just before the modal is activated
- To place the focus inside of the dialog on activating the modal, set the dialog focus using the `initialFocus` prop with boolean prop `focusDialog` set to `false`

### Learn more

- [Making an accessible dialog box](https://www.nczonline.net/blog/2013/02/12/making-an-accessible-dialog-box/)
- [GOV.UK modal dialog boxes discussion](https://paper.dropbox.com/doc/Modal-dialog-boxes-jbsTPoITg37IIc6ybjetM)
- [Overuse of Overlays: How to Avoid Misusing Lightboxes](https://www.nngroup.com/articles/overuse-of-overlays/)
- [Using ARIA role=dialog to implement a modal dialog box](https://www.w3.org/WAI/GL/wiki/Using_ARIA_role%3Ddialog_to_implement_a_modal_dialog_box)

### Related patterns

- [Alert](/components/alert/)