Layout

Modal

Modals are layout panels that present critical information, or request the user’s input, without navigating away from the current page.

Status

Supported

Introduced

v3.8.0

View code View Storybook View Design

Interactive demo

This demo lets you 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 one required element and four optional elements.

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. title)	Block
4	Close button	Icon button for closing the modal	Icon button
5	Content	An area to display any content (e.g. form)	Block

Options

The modal has options 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. Any content passed to the modal panel causes it to grow from the centre until it reaches the max height.
md/lg/xl
The modal is positioned horizontally in the centre of the screen and positioned vertically offset from the top of the screen. Any content passed to the modal panel causes it to grow downwards until it reaches the max height.

Close button position

Position the close button on the right (default) or left of the modal header.

The header and close button are optional. However, you should always include a close button to adhere to ARIA principles.

Width

Customise the width of a modal for each breakpoint to allow for more or less space as needed.

Focus trapping

You can specify the tab order of interactive elements inside the modal. Focus is trapped inside the modal until the user closes it.

There is no focus trapping when the overlay is hidden (modeless).

Overlay

Set the modal overlay to visible or hidden.

Placement

The modal appears as follows across different breakpoints:

xs/sm
The modal is positioned in the centre of the screen. Any content passed to the modal panel causes it to grow from the centre until it reaches the max height.
md/lg/xl
The modal is positioned horizontally in the centre of the screen and positioned vertically offset from the top of the screen. Any content passed to the modal panel causes it to grow downwards until it reaches the max height.

Close button position

Position the close button on the right (default) or left of the modal header.

The header and close button are optional. However, you should always include a close button to adhere to ARIA principles.

Width

Customise the width of a modal for each breakpoint to allow for more or less space as needed.

Focus trapping

You can specify the tab order of interactive elements inside the modal. Focus is trapped inside the modal until the user closes it.

There is no focus trapping when the overlay is hidden (modeless).

Overlay

Set the modal overlay to visible or hidden.

Behaviours

Here’s how the modal behaves:

Height

The height of a modal panel is calculated as a percentage of the available screen. The modal panel grows vertically to fit the content passed into it, until it reaches the max height.

Entrance and exit motion

When the user launches the modal, 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 user dismisses the modal, the same animation occurs in reverse.

Triggering and closing the modal

Control visibility via the open prop (the modal is hidden by default). To close the modal, the user can click the close button or overlay, or press the Esc key. Any of these actions will trigger the onDismiss callback.

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 isn’t scrollable (scroll-locked).

Height

The height of a modal panel is calculated as a percentage of the available screen. The modal panel grows vertically to fit the content passed into it, until it reaches the max height.

Entrance and exit motion

Triggering and closing the modal

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 isn’t scrollable (scroll-locked).

Usage

Here’s how and when to use the modal:

Use modals for critical information

Modals are appropriate for notifications that give the user critical information related to a task. For non-critical information, consider a toast or inline notification instead.

Don’t use modals for marketing

Avoid using modals for marketing or advertising purposes. They’re intended for critical information or requests for user input.

Keep modals close to related content

A modal should be in close proximity to the content it relates to.

Accessibility considerations

The modal 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, focussing on any interactive elements
3	closeButton	Focusses to the close button in the header

Upon opening, focus transfers to the first interactive element in the specified order (i.e. if there are interactive elements passed to the header, this will be the first focussable element).

You can change the element that gets focus by adding a data-autofocus attribute to another HTML element.

Keyboard Interactions

Command	Description
Tab	When the modal is active, it maintains focus trapping. The user will only be able to tab through it and its children
shift Tab	Focusses to 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 information can be crawled and indexed by search engines.
The modal and its content are rendered to the DOM but only visible to the user when the modal is open.

API

Modal

The modal has a range of props to define the experience in different use cases, and a range of predefined elements and attributes that you can override to define their appearance.

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, invokes a callback on dismissing the modal by clicking the close button or overlay, or pressing the Esc key
header	React.ReactNode		If provided, sets the content of the modal header
closePosition	left right none		If provided, sets the position of the close button
restoreFocusTo	HTMLElement		If provided, returns focus to the specified element after the modal is closed. If not provided, focus returns to the element that was focussed before the modal opened
disableFocusTrap	boolean		If true, focus can leave the modal window by tabbing, or clicking directly on the main content
inline	boolean		If true, the modal displays inline using position absolute (instead of fixed) and takes the size of its container

The modal has a range of props to define the experience in different use cases, and a range of predefined elements and attributes that you can override to define their appearance.

Attribute	Type	Default	Description
overlay .stylePreset	MQ<string>	overlay	If provided, overrides the style preset applied to the overlay
panel .stylePreset	MQ<string>	modalPanel	If provided, overrides the style preset applied to the modal panel
panel .topOffset	MQ<string>	20vh	If provided, offsets the modal panel from the top of the screen. 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 button
panel .width	MQ<string>	xs = 90% sm = 60% md = 45% lg = 38% xl = 31%	If provided, overrides the width property of the modal panel
panel .maxWidth	MQ<string>		If provided, overrides the maxWidth property of the modal panel
panel .minWidth	MQ<string>		If provided, overrides the minWidth property of the modal panel
panel .height	MQ<string>	all: '80%'	If provided, overrides the height property of the modal panel
panel .minHeight	MQ<string>	all: '15%'	If provided, overrides the minHeight property of the modal panel
panel .maxHeight	MQ<string>	xs>: 95% md>: 80%	If provided, overrides the maxHeight property of the modal pane
panel .paddingInline	MQ<string>		Takes one space token to specify the logical inline start and end padding of the container. Can be used on breakpoints
panel .paddingInlineStart	MQ<string>		Takes one space token to specify the logical inline start padding of the container. Can be used on breakpoints
panel .paddingInlineEnd	MQ<string>		Takes one space token to specify the logical inline end padding of the container. Can be used on breakpoints
panel .paddingBlock	MQ<string>		Takes one space token to specify the logical block start and end padding of the container. Can be used on breakpoints
panel .paddingBlockStart	MQ<string>		Takes one space token to specify the logical block start padding of the container. Can be used on breakpoints
panel .paddingBlockEnd	MQ<string>		Takes one space token to specify the logical block end padding of the container. Can be used on breakpoints
header .paddingInline	MQ<string>	space050	Takes one space token to specify the logical inline start and end padding of the container. Can be used on breakpoints
header .paddingInlineStart	MQ<string>		Takes one space token to specify the logical inline start padding of the container. Can be used on breakpoints
header .paddingInlineEnd	MQ<string>		Takes one space token to specify the logical inline end padding of the container. Can be used on breakpoints
header .paddingBlock	MQ<string>	space040	Takes one space token to specify the logical block start and end padding of the container. Can be used on breakpoints
header .paddingBlockStart	MQ<string>		Takes one space token to specify the logical block start padding of the container. Can be used on breakpoints
header .paddingBlockEnd	MQ<string>		Takes one space token to specify the logical block end padding of the container. Can be used on breakpoints
header .marginInline	MQ<string>		Takes one space token to specify the logical inline start and end margin of the container. Can be used on breakpoints
header .marginInlineStart	MQ<string>		Takes one space token to specify the logical inline start margin of the container. Can be used on breakpoints
header .marginInlineEnd	MQ<string>		Takes one space token to specify the logical inline end margin of the container. Can be used on breakpoints
header .marginBlock	MQ<string>		Takes one space token to specify the logical block start and end margin of the container. Can be used on breakpoints
header .marginBlockStart	MQ<string>		Takes one space token to specify the logical block start margin of the container. Can be used on breakpoints
header .marginBlockEnd	MQ<string>		Takes one space token to specify the logical block end margin of the container. Can be used on breakpoints
content .paddingInline	MQ<string>	space050	Takes one space token to specify the logical inline start and end padding of the container. Can be used on breakpoints
content .paddingInlineStart	MQ<string>		Takes one space token to specify the logical inline start padding of the container. Can be used on breakpoints
content .paddingInlineEnd	MQ<string>		Takes one space token to specify the logical inline end padding of the container. Can be used on breakpoints
content .paddingBlock	MQ<string>	space050	Takes one space token to specify the logical block start and end padding of the container. Can be used on breakpoints
content .paddingBlockStart	MQ<string>		Takes one space token to specify the logical block start padding of the container. Can be used on breakpoints
content .paddingBlockEnd	MQ<string>		Takes one space token to specify the logical block end padding of the container. Can be used on breakpoints
content .marginInline	MQ<string>		Takes one space token to specify the logical inline start and end margin of the container. Can be used on breakpoints
content .marginInlineStart	MQ<string>		Takes one space token to specify the logical inline start margin of the container. Can be used on breakpoints
content .marginInlineEnd	MQ<string>		Takes one space token to specify the logical inline end margin of the container. Can be used on breakpoints
content .marginBlock	MQ<string>		Takes one space token to specify the logical block start and end margin of the container. Can be used on breakpoints
content .marginBlockStart	MQ<string>		Takes one space token to specify the logical block start margin of the container. Can be used on breakpoints
content .marginBlockEnd	MQ<string>		Takes one space token to specify the logical block end margin of the container. Can be used on breakpoints
closeButton .stylePreset	MQ<string>	iconButtonMinimalSecondary	If provided, overrides the style preset applied to the modal close button
closeButton .paddingInline	MQ<string>	space020	Takes one space token to specify the logical inline start and end padding of the container. Can be used on breakpoints
closeButton .paddingInlineStart	MQ<string>		Takes one space token to specify the logical inline start padding of the container. Can be used on breakpoints
closeButton .paddingInlineEnd	MQ<string>		Takes one space token to specify the logical inline end padding of the container. Can be used on breakpoints
closeButton .paddingBlock	MQ<string>	space020	Takes one space token to specify the logical block start and end padding of the container. Can be used on breakpoints
closeButton .paddingBlockStart	MQ<string>		Takes one space token to specify the logical block start padding of the container. Can be used on breakpoints
closeButton .paddingBlockEnd	MQ<string>		Takes one space token to specify the logical block end padding of the container. Can be used on breakpoints
closeButton .marginInline	MQ<string>		Takes one space token to specify the logical inline start and end margin of the container. Can be used on breakpoints
closeButton .marginInlineStart	MQ<string>		Takes one space token to specify the logical inline start margin of the container. Can be used on breakpoints
closeButton .marginInlineEnd	MQ<string>		Takes one space token to specify the logical inline end margin of the container. Can be used on breakpoints
closeButton .marginBlock	MQ<string>		Takes one space token to specify the logical block start and end margin of the container. Can be used on breakpoints
closeButton .marginBlockStart	MQ<string>		Takes one space token to specify the logical block start margin of the container. Can be used on breakpoints
closeButton .marginBlockEnd	MQ<string>		Takes one space token to specify the logical block end margin of the container. Can be used on breakpoints
zIndex	number	80	If provided, overrides the zIndex of the modal
overlay .zIndex	number	70	If provided, overrides the zIndex of the overlay

Need Help?

Cant find what you are looking for?

Get In Touch

Need Help?

Cant find what you are looking for?

Get In Touch

Modal

Status

Introduced

Interactive demo

Anatomy

Options

Placement

Close button position

Width

Focus trapping

Overlay

Placement

Close button 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

Accessibility considerations

SEO considerations

API

Related components

Block

Divider

Drawer

Popover

Need Help?

Need Help?