Newskit Logo

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
View code

Status

Supported

Introduced

Interactive Demo

This demo allows you to preview the Modal component, its variations, and configuration options.

Use props bellow to open and configure the modal.

open
closePosition
hideOverlay
1import React from 'react';
2import { Modal } from 'newskit';
3
4export default () => <Modal header="" />;
5

Anatomy

The Modal contains four required elements and one optional element.

ItemNameDescriptionComponentOptional
1
OverlayObscures the page content behind the panel
Overlay (internal)
2
PanelContains the Panel Header and Panel ContentBlock
3
HeaderAn area to display content at the top of a panel e.g. a titleBlock
4
Close buttonIcon Button for closing the ModalIcon Button
5
ContentAn area to display any content e.g. a formBlock

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

The position of the close button in the Modal header is set to right as default, with the option to set the position to the left of the header.

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

The position of the close button in the Modal header is set to right as default, with the option to set the position to the left of the header.

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

open
prop on the component, hidden by default.

To handle closing the Modal the user will need to supply and handle via the
onDismiss
callback. This will be triggered when the user clicks on the close Icon Button, the overlay, or by pressing the Esc keyboard key.

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

open
prop on the component, hidden by default.

To handle closing the Modal the user will need to supply and handle via the
onDismiss
callback. This will be triggered when the user clicks on the close Icon Button, the overlay, or by pressing the Esc keyboard key.

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.

Do not

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:

Focus order
OrderElementRole
1
headerFocusses to the content (children) passed to the header area, focusing on any interactive elements.
2
contentFocusses to the content (children) passed to the content area, focusing on any interactive elements.
3
closeButtonFocusses to the close Icon Button in the header.

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.

Keyboard Interactions
CommandDescription
Tab
When the Modal is active it will maintain focus trapping. The user will only be able to tab through it and its children.
shift
Tab
Focuses the previous link or action in the Modal (if provided).
Esc
Closes the Modal and overlay.
WAI-ARIA
ElementAttributeValueDescriptionUser Supplied
Modal
ariaLabelledby
string
Defines the Aria-label of the Modal
Modal
ariaDescribedby
string
Describes the purpose of the Modal
Modal
ariaModal
boolean
Defines the Modal dialog

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.

NameTypeDefaultDescriptionRequired
children
Exclude<React.ReactNode, 'undefined'>
Displays supplied content in the Modal panel content area.
open
boolean
false
Determines if the Modal is open.
onDismiss
function
If provided, a callback which is invoked on dismissing the Modal through either clicking the close Icon Button, overlay, or pressing the Esc key.
header
React.ReactNode
If provided sets the content of the Modal header.
closePosition
left | right
If provided, sets the position of the close icon button.
restoreFocusTo
HTMLElement
If provided, returns focus to the specified element after the Modal is closed. If not provided, focus will return to the focused element prior to the Modal opening.
disableFocusTrap
boolean
If true, focus can leave the modal window through tabbing or direct click on the main content.
inline
boolean
If true,the modal will display inline using position absolute ( instead of fixed ) and will take the size of its container

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.

FeatureDescriptionStatus
VariationsRelevant variations (style, size, orientation etc.)
Interactive statesAll interactive states that are applicable (hover, active, focus, focus, disabled, error etc).
Defined behavioursGuidelines for layout, animation, interactions, etc.
Usage guidelinesIncludes a list of dos and don’ts that highlight best practices and common mistakes to avoid.
Accessibility guidelinesFollows WCAG 2.0 standards (AA). Accessibility documentation defined including focus order, keyboard interactions and ARIA.
SEO guidelinesConforms to best practice SEO techniques. SEO considerations defined.
PropsDetails of component properties - their name, type, options, default, whether it’s required and their description have been defined.
Technical performance considerationsDetails on how this component may impact performance.
Available in UI kitIncluded within Figma Web Gallery file.
Design specificationsDetailed design specification including sizing, spacing and design tokens defined.
ThemesDisplays correctly across light and dark themes.

Need Help?

Cant find what you are looking for?

Cant find what you are looking for?