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

View Design

Status

Supported

Introduced

v3.8.0

View code

View Design

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.

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.

Item	Name	Description	Component
1	Overlay	Obscures the page content behind the panel	Overlay (internal)
2	Panel	Contains the Panel Header and Panel Content	Block
3	Header	An area to display content at the top of a panel e.g. a title	Block
4	Close button	Icon Button for closing the Modal	Icon Button
5	Content	An area to display any content e.g. a form	Block

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

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

Entrance and exit motion

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

Order	Element	Role
1	header	Focusses to the content (children) passed to the header area, focusing on any interactive elements.
2	content	Focusses to the content (children) passed to the content area, focusing on any interactive elements.
3	closeButton	Focusses 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

Command	Description
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

Element	Attribute	Value	Description
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.

Name	Type	Default	Description
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

The Modal has a range of predefined elements and attributes that can be overridden to define their appearance.

Attribute	Type	Default	Description
overlay .stylePreset	MQ<string>	overlay	If provided, this overrides the style preset applied to the Overlay.
modal .panel .stylePreset	MQ<string>	modalPanel	If provided, this overrides the style preset applied to the Modal panel.
modal .panel .topOffset	MQ<string>	20vh	If provided, the Modal panel is offset from the top of the screen. Note - There is no topOffset applied to mobile breakpoints, as it grows from the centre until the max height is reached. If provided, sets the position of the close icon button.
modal .panel .width	MQ<string>	xs = 90% sm = 60% md = 45% lg = 38% xl = 31%	If provided, this overrides the width property of the Modal panel.
modal .panel .maxWidth	MQ<string>		If provided, this overrides the maxWidth property of the Modal panel.
modal .panel .minWidth	MQ<string>		If provided, this overrides the minWidth property of the Modal panel.
modal .panel .height	MQ<string>	all: '80%'	If provided, this overrides the height property of the Modal panel.
modal .panel .minHeight	MQ<string>	all: '15%'	If provided, this overrides the minHeight property of the Modal panel.
modal .panel .maxHeight	MQ<string>	xs>: 95% md>: 80%	If provided, this overrides the maxHeight property of the Modal panel.
modal .header .stylePreset	MQ<string>	spaceInsetSquish040	If provided, this overrides the padding space set in Modal header content container.
modal .content .spaceInset	MQ<string>	spaceInset050	If provided, this overrides the padding space set in Modal content container.
modal .closeButton .stylePreset	MQ<string>	iconButtonMinimalSecondary	If provided, this overrides the style preset applied to the Modal close Icon Button.
modal .closeButton .spaceInset	MQ<string>	spaceInset020	If provided, this overrides the padding space set in the Modal close Icon Button.
modal .zIndex	number	80	If provided, this overrides the zIndex of the Modal.
overlay .zIndex	number	70	If provided, this overrides the zIndex of the Overlay.

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
Variations	Relevant variations (style, size, orientation etc.)
Interactive states	All interactive states that are applicable (hover, active, focus, focus, disabled, error etc).
Defined behaviours	Guidelines for layout, animation, interactions, etc.
Usage guidelines	Includes a list of dos and don’ts that highlight best practices and common mistakes to avoid.
Accessibility guidelines	Follows WCAG 2.0 standards (AA). Accessibility documentation defined including focus order, keyboard interactions and ARIA.
SEO guidelines	Conforms to best practice SEO techniques. SEO considerations defined.
Props	Details of component properties - their name, type, options, default, whether it’s required and their description have been defined.
Technical performance considerations	Details on how this component may impact performance.
Available in UI kit	Included within Figma Web Gallery file.
Design specifications	Detailed design specification including sizing, spacing and design tokens defined.
Themes	Displays correctly across light and dark themes.

Need Help?

Cant find what you are looking for?

Need Help?

Cant find what you are looking for?

Modal

Status

Introduced

Status

Introduced

Interactive Demo

Anatomy

Options

Placement

Close position

Width

Focus trapping

Overlay

Placement

Close position

Width

Focus trapping

Overlay

Behaviours

Height

Entrance and exit motion

Triggering and closing the modal

Content overflow

Lock scroll

Height

Entrance and exit motion

Triggering and closing the modal

Content overflow

Lock scroll

Usage

Do

Do not

Do

Accessibility Considerations

SEO Considerations

API

Compliance

Related Components

Drawer

Menu

Need Help?

Need Help?