<Modal>
npm i @accessible/modal
An accessible and versatile modal component for React
Features
Quick Start
Check out the example on CodeSandbox
import * as React from 'react'
import * as Modal from '@accessible/modal'
const Component = () => (
<Modal.Modal>
<Modal.Trigger>
<button>Open me</button>
</Modal.Trigger>
<Modal.Target>
<div className='my-modal'>
<Modal.CloseButton>
<button>Close me</button>
</Modal.CloseButton>
<div>You did a thing</div>
</div>
</Modal.Target>
</Modal.Modal>
)
API
Components
Component | Description |
---|
<Modal> | This component creates the context for your modal target and trigger and contains some configuration options. |
<Target> | This component wraps any React element and turns it into a modal target. |
<Trigger> | This component wraps any React element and turns it into a modal trigger. |
<CloseButton> | This is a convenience component that wraps any React element and adds an onClick handler to close the modal. |
Hooks
<Modal>
This component creates the context for your modal target and trigger and contains some
configuration options.
Props
Prop | Type | Default | Required? | Description |
---|
defaultOpen | boolean | false | No | This sets the default open state of the modal. By default the modal is closed. |
open | boolean | undefined | No | This creates a controlled modal component where the open state of the modal is controlled by this property. |
onChange | (open: boolean) => void | undefined | No | This callback is invoked any time the open state of the modal changes. |
id | string | undefined | No | By default this component creates a unique id for you, as it is required for certain aria attributes. Supplying an id here overrides the auto id feature. |
children | React.ReactNode | undefined | No | Your modal contents and any other children. |
useA11yTarget(target, options?)
A React hook for creating a headless modal target to WAI-ARIA authoring practices.
Arguments
Argument | Type | Required? | Description |
---|
target | React.RefObject<T> | T | null | Yes | A React ref or HTML element |
options | UseA11yTargetOptions | No | Configuration options |
UseA11yTargetOptions
export interface UseA11yTargetOptions {
openClass?: string
closedClass?: string
openStyle?: React.CSSProperties
closedStyle?: React.CSSProperties
preventScroll?: boolean
closeOnEscape?: boolean
}
Returns
interface A11yProps {
readonly role: 'dialog'
readonly 'aria-hidden': boolean
readonly id: string | undefined
readonly className: string | undefined
readonly style: {
readonly visibility: 'hidden' | 'visible'
readonly position: 'fixed'
readonly margin: 'auto'
readonly left: '50%'
readonly top: '50%'
readonly transform: 'translate3d(-50%, -50%, 0)'
}
}
Example
import * as React from 'react'
import {useA11yTarget} from '@accessible/modal'
const MyTarget = () => {
const ref = React.useRef(null)
const a11yProps = useA11yTarget(ref, {closeOnEscape: false})
return (
<div ref={ref} {...a11yProps}>
I am the modal dialog
</div>
)
}
<Target>
This component wraps any React element and turns it into a modal target.
Props
Prop | Type | Default | Required? | Description |
---|
portal | boolean | string | PortalizeProps | false | No | When true this will render the modal into a React portal with the id #portals . You can render it into any portal by providing its query selector here, e.g. #foobar , [data-portal=true] , or .foobar . |
closeOnEscape | boolean | true | No | By default the modal will close when the Escape key is pressed. You can turn this off by providing false here. |
closedClass | string | undefined | No | This class name will be applied to the child element when the modal is closed . |
openClass | string | undefined | No | This class name will be applied to the child element when the modal is open . |
closedStyle | React.CSSProperties | undefined | No | These styles will be applied to the child element when the modal is closed in addition to the default styles that set the target's visibility. |
openStyle | React.CSSProperties | undefined | No | These styles name will be applied to the child element when the modal is open in addition to the default styles that set the target's visibility. |
preventScroll | boolean | false | No | When true this will prevent your browser from scrolling the document to bring the newly-focused tab into view. |
children | React.ReactElement | undefined | Yes | The child is cloned by this component and has aria attributes injected into its props as well as the events defined above. |
Example
<Target>
<div className='alert'>Alert</div>
</Target>
useA11yTrigger(target, options?)
A React hook for creating a headless modal trigger to WAI-ARIA authoring practices.
In addition to providing accessibility props to your component, this hook will add events
for interoperability between actual elements and fake ones e.g. and
to the
target element
Arguments
Argument | Type | Required? | Description |
---|
target | React.RefObject<T> | T | null | Yes | A React ref or HTML element |
options | UseA11yTriggerOptions | No | Configuration options |
UseA11yTriggerOptions
export interface UseA11yTriggerOptions {
openClass?: string
closedClass?: string
openStyle?: React.CSSProperties
closedStyle?: React.CSSProperties
onClick?: (e: MouseEvent) => any
}
Returns
interface A11yProps<E extends React.MouseEvent<any, MouseEvent>> {
readonly 'aria-haspopup': 'dialog'
readonly 'aria-controls': string | undefined
readonly 'aria-expanded': boolean
readonly role: 'button'
readonly tabIndex: 0
readonly className: string | undefined
readonly style: React.CSSProperties | undefined
}
Example
import * as React from 'react'
import {useA11yTrigger} from '@accessible/modal'
const MyTrigger = () => {
const ref = React.useRef(null)
const a11yProps = useA11yTrigger(ref, {
openClass: 'open',
closedClass: 'closed',
})
return (
<button ref={ref} {...a11yProps}>
Clicking me toggles the modal dialog
</button>
)
}
<Trigger>
This component wraps any React element and adds an onClick
handler which toggles the open state
of the modal target.
Props
Prop | Type | Default | Required? | Description |
---|
closedClass | string | undefined | No | This class name will be applied to the child element when the modal is closed . |
openClass | string | undefined | No | This class name will be applied to the child element when the modal is open . |
closedStyle | React.CSSProperties | undefined | No | These styles will be applied to the child element when the modal is closed . |
openStyle | React.CSSProperties | undefined | No | These styles name will be applied to the child element when the modal is open . |
children | React.ReactElement | undefined | Yes | The child is cloned by this component and has aria attributes injected into its props as well as the events defined above. |
<Trigger on='click'>
<button className='my-button'>Open me!</button>
</Trigger>
useA11yCloseButton(target, options?)
A React hook for creating a headless close button to WAI-ARIA authoring practices.
In addition to providing accessibility props to your component, this hook will add events
for interoperability between actual
elements and fake ones e.g.
and to the
target element
Arguments
Argument | Type | Required? | Description |
---|
target | React.RefObject<T> | T | null | Yes | A React ref or HTML element |
options | UseA11yCloseButtonOptions | No | Configuration options |
UseA11yCloseButtonOptions
export interface UseA11yCloseButtonOptions {
onClick?: (e: MouseEvent) => any
}
Returns
interface A11yProps<E extends React.MouseEvent<any, MouseEvent>> {
readonly 'aria-haspopup': 'dialog'
readonly 'aria-controls': string | undefined
readonly 'aria-expanded': boolean
readonly 'aria-label': 'Close'
readonly role: 'button'
readonly tabIndex: 0
}
Example
import * as React from 'react'
import {useA11yCloseButton} from '@accessible/modal'
const MyTrigger = () => {
const ref = React.useRef(null)
const a11yProps = useA11yCloseButton(ref, {
onClick: () => console.log('Closing!'),
})
return (
<button ref={ref} {...a11yProps}>
Clicking me closes the modal dialog
</button>
)
}
<CloseButton>
This is a convenience component that wraps any React element and adds an onClick handler which closes the modal.
Props
Prop | Type | Default | Required? | Description |
---|
children | React.ReactElement | undefined | Yes | The child is cloned by this component and has aria attributes injected into its props as well as the events defined above. |
<CloseButton>
<button className='my-button'>Close me</button>
</CloseButton>
useModal()
This hook provides the value of the modal's ModalContextValue object
ModalContextValue
export interface ModalContextValue {
isOpen: boolean
open: () => void
close: () => void
toggle: () => void
id?: string
}
Example
const Component = () => {
const {open, close, toggle, isOpen} = useModal()
return <button onClick={toggle}>Toggle the modal</button>
}
LICENSE
MIT