A dialog is a window overlaid on either the primary window or another dialog window. Content behind a modal dialog is inert, meaning that users cannot interact with it.
🚨 Version (v1.0.0) introduced a breaking change to this component's API. Kindly update accordingly.
Chakra exports 7 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 elements, focus is set on
When the dialog closes, it returns focus to the element that triggered it. Set
finalFocusRef to change the element that should receive focus when the modal
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 the modal.
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
falseso it doesn't return focus to the element that triggered it.
By default, the modal closes when you click its overlay. You can set
false if you want the modal to stay visible.
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.
Modal comes with a scale transition by default but you can change it by
motionPreset prop, and set its value to either
If the content within the modal overflows beyond the viewport, you can use the
scrollBehavior to control how scrolling should happen.
inside, scroll only occurs within the
outside, the entire
ModalContentwill scroll within the viewport.
size prop if you need to adjust the size of the modal. Values can be
When the modal is open, it's rendered within a portal and all its siblings have
aria-hidden set to
true so the only thing screen readers see is the modal.
To disable this behavior, set
By default the modal, alert dialog and drawer locks the focus inside them. Normally this is what you want to maintain accessibility standards.
While strongly discourage this use case due to it's accessibility impacts, there are certain situations where you might not want the modal to trap focus.
To prevent focus trapping, pass
trapFocus and set it's value to
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
|onClose||Callback invoked to close the modal.|
|motionPreset||The default animation or transition to apply to 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 closed|
|useInert||A11y: If |
|children||The content of the modal.|
|size||The size (maxWidth) of the modal.|
|scrollBehavior||Where scroll behaviour should originate.|
|id||The top-level |
|onOverlayClick||Function called when the overlay clicked|
|onEsc||Function called when the |