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 |