Skip to main content

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 is the parent component for all other components, it exposes the context and is required.

PropsDefaultTypeDescription
isOpenfalseBooleanFor controlled state, the isOpen property is required and controls the state of the component
setIsOpen-FunctionRequired for component state control ability
persistOnOpenfalseBooleanWhen set to true, outside clicks on modal do not close the modal but modal can still be closed using the close component
initialFocusfirstFocusableReact.MutableRefObjectHandles component to receive first focus when the modal is opened. Must be a focuable element
as'button'HTMLElementThis 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

PropsDefaultTypeDescription
as'button'HTMLElementThis 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.

PropsDefaultTypeDescription
as'span'HTMLElementThis grants the ability to change the element this component should render as

Title​

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

PropsDefaultTypeDescription
as'h2'HTMLElementThis 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.

PropsDefaultTypeDescription
as'h2'HTMLElementThis grants the ability to change the element this component should render as

Close​

Close tag triggers the close of the modal component.

PropsDefaultTypeDescription
as'h2'HTMLElementThis grants the ability to change the element this component should render as