@asphalt-react/modal

Modal

Modal provides a dialog interface to confirm user actions or to communicate an important message and get a response while maintaining the context of the current view. Modal interrupts a user's workflow by design. Modal blocks the user's access to the on-page content while it's visible. When visible, modal also disables the scroll on the body element and enables it when closed.

Modal is a controlled component and does not manage visibility state on it's own. Modal appears towards the top of the viewport by default but you can place it in center as well.

Usage

While effective when used correctly, use Modals sparingly to limit disruption to the user.

import { Modal } from "@asphalt-react/modal"

function App() {
  const [open, setOpen] = React.useState(false)

  return (
    <Modal
      open={open}
      onClose={() => {
        setOpen(false)
      }}
    >
      <span>Are you sure</span>
    </Modal>
  )
}

Helper Components

Modal exports few additional components to render content. These components help create confirmation dialogs easily.

• Title - Use it to render the Modal title.
• Description - Use it to render the Modal description.
• Footer - Use it to render the Modal footer.

import { Modal, Title, Description, Footer } from "@asphalt-react/modal"

function App() {
  const [open, setOpen] = React.useState(false)

  return (
    <Modal
      open={open}
      onClose={() => {
        setOpen(false)
      }}
    >
      <Title>Confirm</Title>
      <Title>Are you sure</Title>
      <Footer>
        <Button>Yes</Button>
        <Button
          onClick={() => {
            setOpen(false)
          }}
        >
          No
        </Button>
      </Footer>
    </Modal>
  )
}

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.

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. 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

children

React Node for modal content.

type	required	default
node	false	null

open

Controls the visibility of the modal.

type	required	default
bool	false	false

bezel

Adds padding inside modal.

type	required	default
bool	false	true

closeOnEsc

Closes modal on ESC keypress.

type	required	default
bool	false	true

center

Places the modal in the center of the viewport.

type	required	default
bool	false	false

onClose

Function to call when modal closes.

type	required	default
func	false	null

bodyScrollLock

Prevents the content behind the Modal from scrolling when the Modal is visible.

type	required	default
bool	false	true

dismiss

Add a cross button to the top right of the modal.

type	required	default
bool	false	false

Title

Title renders a heading for the Modal's content.

Props

children

Title of the modal.

type	required	default
node	false	null

separate

Adds a margin to separate it from its sibling elements.

type	required	default
bool	false	true

Description

Description renders the content for the Dialog.

Props

children

Node for content

type	required	default
node	false	null

separate

Adds a margin to separate it from its sibling elements.

type	required	default
bool	false	true

Footer

Use Footer to add interactive elements in Modal to accept user actions.

Props

children

Node for content.

type	required	default
node	false	null

alignCenter

Places the content at center.

type	required	default
bool	false	false

alignEnd

Places the content at the end.

type	required	default
bool	false	false

ModalLegacy

Modal uses the "dialog" element which is well supported on all major browsers. This is still a fairly new API which the browsers vendors added recently. If you have users that use older browsers which lack support for the "dialog" element, use the ModalLegacy component to wrap the Modal component.

Usage

import { Modal, ModalLegacy } from "@asphalt-react/modal"

export const App = () => {
  const modalRef = React.useRef(null)

  return (
    <ModalLegacy modalRef={modalRef}>
      <Modal open={true} ref={modalRef}>Lorem ipsum</Modal>
    </ModalLegacy>
  )
}

Props

children

Modal to render in older browsers.

type	required	default
node	false	N/A

modalRef

React ref of the Modal.

type	required	default
union	false	N/A