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.
🚨 Version (v0.3.2) introduced a breaking change to this component's API. Kindly update accordingly.
Chakra exports 8 components to help you create any modal dialog.
Modal: The wrapper that provides context for its children
ModalOverlay: The dimmed overlay behind the modal dialog
ModalContent: The container for the modal dialog's content
ModalHeader: The header that labels the modal dialog
ModalFooter: The footer that houses the modal actions
ModalBody: The wrapper that houses the modal's main content
ModalCloseButton: The button that closes the modal.
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
Control Focus when Modal closes#
When the dialog closes, it returns focus to the element that triggered. Set
finalFocusRef to element that should receive focus when the modal opens.
Block Scrolling when Modal opens#
For accessibility, it's recommended to block scrolling on the main document
behind the modal. Chakra does this by default but you can set
false to allow scrolling behind modal.
Focus on specific element#
Chakra automatically sets focus on the first tabbable element in the modal. However, there might be scenarios where you need to manually control where focus goes.
Chakra provides 2 props for this use-case:
refof the component that receives focus when the modal opens.
refof the component that receives focus when the modal closes.
If you set
finalFocusRef, internally we set
so it doesn't return focus to the element that triggered it.
Close Modal on Overlay Click#
By default, the modal closes when you click it's overlay. You can set
false if you want the modal to stay visible.
Make modal vertically centered#
By default the modal has a vertical offset of
3.75rem which you can change by
top to the
ModalContent. If you need to vertically center the modal,
If the content within the modal overflows beyond the viewport, don't use this prop. Try setting the overflow behavior instead
The modal doesn't come with any transition by default so you can manage this
yourself. Chakra exports two transition components
provide simple transitions.
For some reason, focus doesn't return back to the trigger after the transition
ends. As a walkaround, you might need to set
finalFocusRef to the trigger or
any other element, and set
Modal overflow behavior#
If the content within the modal overflows beyond the viewport, you can use the
scrollBehavior to control how scrolling should happen.
- If set to
inside, scroll only occurs within the
- If set to
outside, the entire
ModalContentwill scroll within the viewport.
size prop if you need to adjust the size of the modal. Values can be
Preserving the scrollbar gap#
By default, scrolling is blocked when the modal opens. This can lead to unpleasant content shift.
To prevent this, pass the
preserveScrollBarGap prop. It applies a
padding-right to the body element that's equal to the width of the browser's
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
Keyboard and Focus Management#
- When the modal opens, focus is trapped within it.
- When the dialog opens, focus is automatically set to the first enabled
element, or the element with the
- When the modal closes, focus returns to the element that was focused just
before the modal activated, or the element with the
- 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.bodyto break it out of the source order and make it easy to add
aria-hiddento its siblings.
aria-labelledbyset to the
aria-describedbyset to the
|isOpen||If true, the modal will open|
|onClose||Callback invoked to close the modal.|
|initialFocusRef||The least destructive action to get focus when dialog is open|
|finalFocusRef||The least destructive action to get focus when dialog is open|
|useInert||A11y: If |
|children||The content of the modal.|
|size||The size (maxWidth) of the modal.|
|scrollBehavior||Where scroll behaviour should originate.|
Proudly made in 🇳🇬
Released under the MIT License.
Copyright © 2019 Segun Adebayo