Layout
Modal
A Modal is a layout panel that presents critical information or requests users input without navigating away from the current page.
Status
Supported
Introduced
v3.8.0
Status
Supported
Introduced
v3.8.0
Anatomy
The Modal contains four required elements and one optional element.
| Item | Name | Description | Component | Optional |
|---|
Options
The Modal has options that can be used to provide an appropriate experience for different use cases.
Placement
The Modal appears as follows across different breakpoints:
xs/sm
the Modal is positioned in the centre of the screen, with any content passed to the Modal panel causing it to grow from the centre until the max height is reached.md/lg/xl
the Modal is positioned horizontally in the centre of the screen, with the Modal positioned vertically offset from the top of the screen, with any content passed to the Modal panel causing it to grow downwards until the max height is reached.
Close position
Note
The header and close button are optional. However it‘s recommended that a close button is always used to adhere to aria-principles.
Width
The width of a Modal can be customised appropriately per breakpoint allowing for more or less space as needed.
Focus trapping
Upon opening, the focus will be transferred to the first interactive element in the specified order ie. if there are interactive elements passed to the header, then this will be the first focusable element.
There is no focus trapping when the overlay is hidden (modeless).
Overlay
The Modal overlay can be set to be visible or hidden.
Placement
The Modal appears as follows across different breakpoints:
xs/sm
the Modal is positioned in the centre of the screen, with any content passed to the Modal panel causing it to grow from the centre until the max height is reached.md/lg/xl
the Modal is positioned horizontally in the centre of the screen, with the Modal positioned vertically offset from the top of the screen, with any content passed to the Modal panel causing it to grow downwards until the max height is reached.
Close position
Note
The header and close button are optional. However it‘s recommended that a close button is always used to adhere to aria-principles.
Width
The width of a Modal can be customised appropriately per breakpoint allowing for more or less space as needed.
Focus trapping
Upon opening, the focus will be transferred to the first interactive element in the specified order ie. if there are interactive elements passed to the header, then this will be the first focusable element.
There is no focus trapping when the overlay is hidden (modeless).
Overlay
The Modal overlay can be set to be visible or hidden.
Behaviours
The following guidance describes how the Modal component behaves.
Height
The height of a Modal panel is based on a calculation of the percentage of the available screen, and also by any content passed to the Modal, causing the Modal panel to grow until the max-height is reached.
Entrance and exit motion
When the Modal is launched, the overlay fades in from 0% to 100% opacity (transitions) and the Modal panel slides upward from the centre of the screen (transforms:translate the x or y axis).
When the Modal is dismissed, the same animation in reverse occurs.
Triggering and closing the modal
The Modal visibility is controlled via the
To handle closing the Modal the user will need to supply and handle via the
Content overflow
When the content is too long to fit, content overflows and Scroll is applied. The header becomes fixed and the content can then independently scroll to bring overflowed content into view.
Lock scroll
When a Modal is present the content behind is not scrollable (scroll-locked).
Height
The height of a Modal panel is based on a calculation of the percentage of the available screen, and also by any content passed to the Modal, causing the Modal panel to grow until the max-height is reached.
Entrance and exit motion
When the Modal is launched, the overlay fades in from 0% to 100% opacity (transitions) and the Modal panel slides upward from the centre of the screen (transforms:translate the x or y axis).
When the Modal is dismissed, the same animation in reverse occurs.
Triggering and closing the modal
The Modal visibility is controlled via the
To handle closing the Modal the user will need to supply and handle via the
Content overflow
When the content is too long to fit, content overflows and Scroll is applied. The header becomes fixed and the content can then independently scroll to bring overflowed content into view.
Lock scroll
When a Modal is present the content behind is not scrollable (scroll-locked).
Usage
The following guidance describes how and when to appropriately use a Modal component.
Do
Modals are appropriate for notifications that provide the user with critical information related to a task.
For non-critical information, consider using a toast or inline notification.
Don’t
Avoid using Modals for marketing or advertising purposes, as they are intended for critical information or requests for user input.
Do
Modals should be in close proximity to the content it’s attributed to.
Accessibility Considerations
The Drawer has the following accessibility considerations:
| Order | Element | Role |
|---|
Upon opening, focus will be transferred to the first interactive element in the specified order ie if there are interactive elements passed to the header, then this will be the first focusable element.
If you want to change the element that gets focus then add a data-autofocus attribute to the HTML element you want to be focused on.
| Command | Description |
|---|
| Element | Attribute | Value | Description | User Supplied |
|---|
SEO Considerations
Ensure all text, icons, and images are visible in the Modal so that information can be crawled and indexed.
The Modal component and its content are rendered to the DOM, but only visible to the user when the Modal is open.
API
The Modal has a range of props that can be used to define an appropriate experience for different use cases.
| Name | Type | Default | Description | Required |
|---|
Compliance
All of the components in the NewsKit design system go through a comprehensive set of checks to ensure that we are producing compliant and best practice components.
| Feature | Description | Status |
|---|