@asphalt-react/modal v1.23.1

Modal

Modal provides an opportunity to confirm user actions or to communicate an important message and acquire a response while maintaining the context of the current view. Modal interrupts a user's workflow by design. When opened, a user is blocked from the on-page content and cannot return to their previous workflow until the modal action is completed or the user dismisses the modal. While effective when used correctly, use modals sparingly to limit disruption to the user.

There are three different sections internal to the modal:

• Header - contains the title of the modal
• Body - describes the primary purpose or message of the modal
• Footer - renders a primary button and a dismiss (secondary) button as the footer. Primary action confirms the user action and secondary action dismisses the modal by default.

Modal uses React Portal and appends a new instance of modal to document.body by default, you can choose to render modal in custom container element using portalRoot prop.

Following props are required for correct functioning of Modal:

• isOpen - to show or hide modal.

• title - a brief text to clearly describe the modal's task or purpose.

• description - to give an overview of modal's purpose

• closeModal - function to close the modal on esc key and dismiss action

When to use

• An immediate response is required from the user:

  Use a modal to request information that is preventing the system from continuing a user-initiated process.

• Confirm a user decision:

  Use a modal to confirm user decisions. Clearly describe the action being confirmed and explain any potential consequences that it may cause. Both the title and the primary button should reflect the action that will occur. If the action is destructive or irreversible then use a danger modal.

When not to use

• Modals prevent access to the main page:

  Don’t use if additional information outside the modal needs to be consulted. While a modal is opened a user cannot interact with the main page and is restricted to only the information inside the modal for making decisions. Modal tasks should be easy to complete with the limited information presented inside the modal itself. If a user needs access to additional information then consider using a full page instead.

• Avoid nesting modals:

  One modal should never trigger another modal. When a modal's task is dependent on another modal then perform the first task outside of a modal.

• Avoid full page modals:

  Avoid using modals to display complex forms or large amounts of information. If a modal needs more space than the component allows then the content should be displayed on a page of its own and not inside a modal. A modal is not an alternative to page.

Usage

import Modal from "@asphalt-react/modal"

function App() {
  const [visible, setVisible] = React.useState(false)

  return (
    <Modal
      isOpen={visible}
      title="Confirm"
      description={<span>Are you sure</span>}
      closeModal={() => setVisible(false)}
    />
  )
}

Danger

Danger variant is best suited for desctructive and irreversible actions. In danger modal, the primary button is replaced by a danger button. This variant follows Alert Dialog Pattern. It sets the role to alertdialog and focuses dismiss button (button to close the modal) when modal opens. This is done so that if a user accidentally hits enter or space when the modal opens no damage is done.

Use danger modal in high impact moments as a confirmation for an action that would result in a significant data loss if done accidentally.

Accessibility

Adds aria-modal attribute to let assistive technologies handle it as a dialog role. By default the first focusable element receives focus when modal opens. dismiss button receives focus first in danger variant. Modal passes aria-* attributes to its topmost element.

For better screen reader support, add an id to the description node and apply it to aria-describedby.

• Use Tab to move focus to the next focusable element inside the modal.
• Use Esc to close the Modal.

Data Attributes

Modal accepts data-* attributes and forwards them to its top level element.

Props

isOpen

Decides if modal is shown or not

closeModal

Function to close the modal on esc key and dismiss action.

title

Title of modal

description

Description of modal

children

React node for modal's body

primaryButtonCaption

Caption for primary button

primaryButtonProps

Props for primary button, accepts props and attributes for Button component except "size" and "danger".

dismissButtonCaption

Caption for dismiss button

dismissButtonProps

Props for dismiss button, accepts props and attributes for Button component except "size", "secondary" and "onClick".

onAfterOpen

Function invoked after modal opens

onAfterClose

Function invoked after modal closes

danger

Renders a danger variant of modal

portalRoot

Function to get container element for the modal. Modal uses ReactDOM.createPortal(child, container) method.