Modals focus the user's attention exclusively on one of peice of information via a window that sits on top of the page content.
- When an immediate response is required from the user.
- To notify the user of urgent information.
- To confirm a user's decision.
- A modal should only be used if it provides the user with critical information immediately related to their task. If you need to provide users with information that is not critical, you should consider using the Notification component instead.
Live example
Availabile platforms
|
Platform |
Available |
|---|---|
|
Figma |
✓ |
|
Web (@ovotech/element) |
✓ |
|
App (@ovotech/element-native) |
❌ |
How to use it
Plain
We use Plain modal to show people information without any actions.
Action
We use Action modal if people need to take actions, e.g. confirm/submit.
Stepped
We use Stepped modal when people need to complete a multi-step journey/task.
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.
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.
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.
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.
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.
Content guidelines
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.
Properties
|
Name |
Values |
Default |
|---|---|---|
|
title (required) |
ReactNode |
|
|
headingComponent |
ComponentType String |
|
|
autoFocus |
boolean |
|
|
isDismissable |
boolean |
|
|
onClose |
Function |
|
|
isOpen |
boolean |
|
Checking for accessibility
User stories
The following user stories can be used to understand when this component should be used, and how to know when it's been implemented correctly.
- As a keyboard-only user, I want focus to be redirected to the modal when it opens, and to the control that opened it when closed.
- As a keyboard-only user, I want to be able to quickly dismiss the modal using the Escape key.
- As a keyboard-only user, I want focus to be contained within the modal when it is open.
- As a screen reader user, I only want content within the modal to be readable when it is open.
- As a screen reader user, I want to be able to understand that I am reading content in a modal, with its role announced as expected, and I want to understand the purpose of the modal, with its name announced.
Test steps
Use these steps to check that the Modal component has been implemented correctly:
- Turn on a screen reader.
- Navigate to the control that opens the modal and activate it.
- Verify that focus is moved to the now open modal.
- Verify that a role of modal is announced, as well as the name of the modal.
- Verify that both focus, and reading order, are limited to only content within the modal and any background content (now obscured by the modal) cannot be reached.
- Verify that when the modal is closed, focus is returned to the control that opened the modal.
Avoiding accessibility barriers
We're aware of the following barriers that can be introduced when using this component. Ensure that you are not adding barriers, by considering the following:
- When styling the modal with a custom background colour, ensure that there is at least a 4.5:1 colour contrast ratio between the text within the modal and the modal's background colour.
Related components
Related patterns
External links
- xxx