Newskit Logo
View Github

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

v3.8.0

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

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.

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

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.

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

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.

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:

Focus order
OrderElementRole

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
WAI-ARIA
ElementAttributeValueDescriptionUser 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.

NameTypeDefaultDescriptionRequired

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

Need Help?

Cant find what you are looking for?

Need Help?

Cant find what you are looking for?