Modals manager
Manage different types of modals with a single easy to use hook.
Props#
useModal.open#
| Prop | Type | Default | Description |
|---|---|---|---|
| allowPinchZoom | boolean | false. | Handle zoom/pinch gestures on iOS devices when scroll locking is enabled. |
| autoFocus | boolean | true | If true, the modal will autofocus the first enabled and interactive
element within the ModalContent |
| blockScrollOnMount | boolean | true | If true, scrolling will be disabled on the body when the modal opens. |
| closeOnEsc | boolean | true | If true, the modal will close when the Esc key is pressed |
| closeOnOverlayClick | boolean | true | If true, the modal will close when the overlay is clicked |
| contentProps | ModalContentProps | Props for the modal content | |
| finalFocusRef | RefObject<FocusableElement> | The ref of element to receive focus when the modal closes. | |
| footer | string | number | bigint | boolean | ReactElement<any, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal | Promise<...> | The modal footer | |
| footerProps | ModalFooterProps | Props for the modal footer | |
| headerProps | ModalHeaderProps | Props for the modal header | |
| hideCloseButton | boolean | Hide the close button | |
| hideOverlay | boolean | Hide the overlay | |
| id | string | The id of the modal | |
| initialFocusRef | RefObject<FocusableElement> | The ref of element to receive focus when the modal opens. | |
| isCentered | boolean | false | If true, the modal will be centered on screen. |
| lockFocusAcrossFrames | boolean | false | Enables aggressive focus capturing within iframes.
- If true: keep focus in the lock, no matter where lock is active
- If false: allows focus to move outside of iframe |
| motionPreset | MotionPreset | scale | The transition that should be used for the modal |
| onClose | (args: {
force?: boolean | undefined
}) => void | Promise<boolean | undefined> | ||
| onCloseComplete | () => void | Fires when all exiting nodes have completed animating out | |
| onEsc | () => void | Callback fired when the escape key is pressed and focus is within modal | |
| onOverlayClick | () => void | Callback fired when the overlay is clicked. | |
| portalProps | Pick<
PortalProps,
"appendToParentPortal" | "containerRef"
> | Props to be forwarded to the portal component | |
| preserveScrollBarGap | boolean | true | If true, a `padding-right` will be applied to the body element
that's equal to the width of the scrollbar.
This can help prevent some unpleasant flickering effect
and content adjustment when the modal opens |
| returnFocusOnClose | boolean | true | If true, the modal will return focus to the element that triggered it when it closes. |
| scope | ModalScopes | ||
| scrollBehavior | ScrollBehavior | outside | Where scroll behavior should originate.
- If set to inside, scroll only occurs within the ModalBody.
- If set to outside, the entire ModalContent will scroll within the viewport. |
| title | string | number | bigint | boolean | ReactElement<any, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal | Promise<...> | The modal title | |
| trapFocus | boolean | true | If false, focus lock will be disabled completely.
This is useful in situations where you still need to interact with
other surrounding elements.
🚨Warning: We don't recommend doing this because it hurts the
accessibility of the modal, based on WAI-ARIA specifications. |
| type | TModalTypes | ||
| useInert | boolean | true | A11y: If true, the siblings of the modal will have `aria-hidden`
set to true so that screen readers can only see the modal.
This is commonly known as making the other elements **inert** |
Was this helpful?