Modal

Overview

Modals focus the user's attention exclusively on one of peice of information via a window that sits on top of the page content. Modals should be used when

• An immediate response is required from the user
• To notify the user of urgent information
• Confirm a user's decision

Usage

Edit live code

Content

Placing content inside a modal can be a useful way of attracting users attention.

When active, a user is blocked from on page content and cannot return to their previous workflow until completed or dismissed, with this in mind modals should be used sparingly to avoid disruption to the user.

The modal will automatically size to accomodate what ever content has been added. If a vertical scroll is neccesssary the page will scroll rather than the modal.

Accessibility

In order to be accessible modals should;

• Refocus the last focused element when the modal is closed
• Close using ESC
• Make the background non-actionable
• Intially focus on the first input, if the modal contains a form
• Return focus to the button used to open the modal if the dialog is dismissed This modal should do these things automatically, but it is a good idea to check when using it.

Usage

OverlayProvider

This component is built using the an external library - react-aria (opens in new window) . The OverlayProvider context provider is required to hide the content outside of the modal from screenreaders.

import { OverlayProvider } from '@react-aria/overlays';

const MyApp = () => <OverlayProvider>Welcome to my app!</OverlayProvider>
import { OverlayProvider } from '@react-aria/overlays';

const MyApp = () => <OverlayProvider>Welcome to my app!</OverlayProvider>

Variations

Custom heading component

Modal uses the Heading2 component by default, but this can be overridden using the headingComponent prop. Use the semantically correct heading level.

Edit live code

Non Dismissable

Removes the dismiss icon from the top right corner and disables dismissal by clicking on the overlay.

Note that this will cause extra friction for users, and if used an alternative method of dismissing the modal should always be added.

Edit live code

Styled

Props passed to the modal are spread by the modal window, therefore it is possible to modify the styles, for example the width. These can also be styled using styled components by using the as polymorphic prop.

Edit live code

With autoFocus

If form elements are added to the modal, this prop ensures that the focus will be on the first input, this is a feature of the react-aria library.

This prop is defaulted to false, as it may not be appropriate in every use case. For example, it may not be appropriate to focus the input if it occurs below a block of text.

Edit live code

Properties

Modal

Tokens

Theme tokens

Related

• React-aria Library (opens in new window) 
• W3.org modal example (opens in new window)