Modal (Dialog)

Fully functional, accessible modal component which overlaid on either the primary window or another dialog window, rendering the content underneath inert. It adheres to the WAI-ARIA Modal specification.

Core Features

• Out of the box accessible
• Keyboard interaction management
• Focus management and lock (trapped focus within modal)
• Controlled or Uncontrolled

Installation

npm i @dorai-ui/modal

or

yarn add @dorai-ui/modal

Basic Example

Controlled State

For more flexibility such as performing an API call before triggering the modal, use the controlled state.

For example, making an API call when the modal is opened and closed

import React from 'React'
import { Modal } from '@dorai-ui/modal'

const ControlledModal = () => {
  const [open, setIsOpen] = React.useState(false)

  const closeAPICall = () => {
    const url = 'https://jsonplaceholder.typicode.com/users'

    fetch(url)
      .then((response) => {
        return response.json()
      })
      .then((data) => {
        console.log(data)
        setIsOpen(false)
      })
      .catch(function (error) {
        console.log(error)
      })
  }

  const openAPICall = () => {
    const url = 'https://jsonplaceholder.typicode.com/users'

    fetch(url)
      .then((response) => {
        return response.json()
      })
      .then((data) => {
        console.log(data)
        setIsOpen(true)
      })
      .catch(function (error) {
        console.log(error)
      })
  }

  const handleOpenState = () => {
    if (open) return closeAPICall()

    openAPICall()
  }

  return (
    <div>
      <Modal isOpen={open} setIsOpen={handleOpenState}>
        <Modal.Trigger />
        <Modal.Group>
          <Modal.Title />
          <Modal.Description />
          <Modal.Close />
        </Modal.Group>
      </Modal>
    </div>
  )
}

Focus Management

When modal is triggered, focus is put on the first focusable element. We can set the component to receive the first focus by using the initialFocus props which accepts a ref.

For Example, the initialFocus is moved to the proceed button below;

import React from 'React'
import { Modal } from '@dorai-ui/modal'

const FocusableDialog = () => {
  const actionRef = React.useRef(null)

  return (
    <div>
      <Modal initialFocus={actionRef}>
        <Modal.Trigger />
        <Modal.Group>
          <Modal.Title />
          <Modal.Description />
          <Modal.Cancel />
          <button ref={actionRef}>Proceed</button>
        </Modal.Group>
      </Modal>
    </div>
  )
}

API

All component accepts default HTML props that are assignable to them. For example, a div cannot accept the href prop but the a tag would.

Components Composed

import { Modal } from '@dorai-ui/modal'

const ModalComp = () => (
  <Modal>
    <Modal.Trigger />
    <Modal.Group>
      <Modal.Title />
      <Modal.Description />
      <Modal.Close />
    </Modal.Group>
  </Modal>
)

Modal (required)

Modal is the parent component for all other components, it exposes the context and is required.

Props	Default	Type	Description
isOpen	false	Boolean	For controlled state, the isOpen property is required and controls the state of the component
setIsOpen	-	Function	Required for component state control ability
persistOnOpen	false	Boolean	When set to true, outside clicks on modal do not close the modal but modal can still be closed using the close component
initialFocus	firstFocusable	React.MutableRefObject	Handles component to receive first focus when the modal is opened. Must be a focuable element
as	'button'	HTMLElement	This grants the ability to change the element this component should render as

Trigger (Optional)

Optional Trigger button is used for the uncontrolled state to trigger the modal. In the controlled state, this can be used and it triggers the function passed to setIsOpen

Props	Default	Type	Description
as	'button'	HTMLElement	This grants the ability to change the element this component should render as

Group

The Group component manages focus lock and exposed certain context value of and it is required.

Props	Default	Type	Description
as	'span'	HTMLElement	This grants the ability to change the element this component should render as

Title

The Title component labels the modal. This is important for Accessiblity.

Props	Default	Type	Description
as	'h2'	HTMLElement	This grants the ability to change the element this component should render as

Description (Optional)

Optional Description component describes the modal component. This enables screen readers to announce the purpose of the modal / dialog but it should be concised.

Props	Default	Type	Description
as	'h2'	HTMLElement	This grants the ability to change the element this component should render as

Close

Close tag triggers the close of the modal component.

Props	Default	Type	Description
as	'h2'	HTMLElement	This grants the ability to change the element this component should render as