Modal (Dialog)
A dialog is a window overlaid on either the primary window or another dialog window. Contents behind a modal dialog are inert meaning that users cannot interact with content behind the dialog.
Import
Usage
When the modal opens, focus is sent into the modal and set to the first tabbable
element. If there are no tabbled element, focus is set on the ModalContent
.
Editable Example
Close Modal on Overlay Click
By default, the modal closes when you click it's overlay. You can set
closeOnOverlayClick
to false
if you want the modal to stay visible.
Editable Example
Block Scrolling when Modal opens
For accessibility, it's recommended to block scrolling on the main document
behind the modal. Search.io does this by default but you can set
blockScroll
to false
to allow scrolling behind modal.
Editable Example
Center Modal Content
By default, the modal content is centered on screens. You can set
center
to false
if you want to keep the dialog on top of the page.
Editable Example
Modal Sizes
Pass the size
prop if you need to adjust the size of the modal. Values can be any of the following:
Value | Max Width |
---|---|
max-w-xs | 20rem |
max-w-sm | 24rem |
max-w-md | 28rem |
max-w-lg | 32rem |
max-w-xl | 36rem |
max-w-2xl | 42rem |
max-w-3xl | 48rem |
max-w-4xl | 56rem |
max-w-5xl | 64rem |
max-w-6xl | 72rem |
max-w-7xl | 80rem |
max-w-screen-sm | 640px |
max-w-screen-md | 768px |
max-w-screen-lg | 1024px |
max-w-screen-xl | 1280px |
max-w-screen-2xl | 1536px |
max-w-full | 100% |
Editable Example
Making other elements Inert
When the modal is open, it's rendered within a portal and all it's siblings have
aria-hidden
set to true
so the only thing screen readers see is the modal.
To disable this behavior, set useInert
to false
.
Accessibility
Keyboard and Focus Management
- When the modal opens, focus is trapped within it.
- Clicking on the overlay closes the Modal.
- Pressing Esc closes the Modal.
- Scrolling is blocked on the elements behind the modal.
- The modal is portalled to the end of
document.body
to break it out of the source order and make it easy to addaria-hidden
to its siblings.
ARIA
- The
ModalContent
hasaria-modal
set totrue
. - The
ModalContent
hasaria-labelledby
set to theid
of theModalTitle
- The
ModalContent
hasaria-describedby
set to theid
of theModalBody
Props
Modal Props
Name | Type | Default | Description |
---|---|---|---|
open | boolean | If true , the modal will open | |
onClose | (event) => void | Callback invoked to close the modal. | |
useInert | boolean | true | A11y: If true , all elements behing the Modal will have aria-hidden set to true so that screen readers can only see the Modal . |
id | string | The id of the modal. | |
ariaLabelledby | string | ARIA label for the modal. | |
ariaDescribedby | string | ARIA description for the modal. | |
fullWidth | boolean | false | If true , the width of the content will be full screen. |
fullHeight | boolean | false | If true , the height of the content will be full screen. |
closeOnEsc | boolean | true | Is the modal closable when user press esc key. |
closeOnOverlayClick | boolean | true | Is the modal closable when user click on overlay. |
blockScroll | boolean | true | Whether to block scrolling when dialog is open. |
center | boolean | true | Should the modal content be centered. |
trapFocus | boolean | true | When the modal is open, trap focus within it. |
initialFocusRef | React.Ref | The ref of the element to receive focus when the dialog opens | |
finalFocusRef | React.Ref | The ref of element to receive focus when the dialog closes | |
returnFocusOnClose | boolean | true | If true , the modal will return focus to the element that triggered it when it closes. |
container | Element | The container where the portal will be rendered inside. | |
size | string | md | The width for the modal content. |
modalId | string | id attribute for modal. | |
onEscKeyDown | (event) => void | Callback fired when the escape key is pressed. | |
onOverlayClick | (event) => void | Callback fired when the overlay is clicked. | |
onAnimationEnd | () => void | Callback fired when the Modal has exited and the animation is finished. | |
zIndex | 2147483647 | 2147483647 | z-index of the modal. |