Usage
useModal hook
useModal hook opens a modal from any component without rendering Modal in JSX.
It accepts Modal props and returns an object with open, close, toggle
and isOpened functions. The modal is rendered by MantineProvider, and all props,
including children, are updated every time the component that called the hook renders:
modal.open accepts props that are applied on top of the hook options until the next modal.open call.
Use it to open the same modal with different content. The content is remounted on every modal.open call
unless keepMounted is set, so a form inside it always starts from its initial values:
useModal can be called in list items, for example, to render a delete confirmation for each table row:
| Name | ||
|---|---|---|
| Ann Smith | ann@mantine.dev | |
| John Doe | john@mantine.dev | |
| Mary Bright | mary@mantine.dev |
useModal accepts the following options in addition to Modal props:
id– modal id, used asidandstackIdof the renderedModal, generated automatically if not setdefaultOpened– initial opened state,falseby defaultonOpen– called when the modal is openedonClose– called when the modal is closed withmodal.close(), close button, overlay click or Escape key
Modals opened with useModal and drawers opened with useDrawer are rendered in one stack,
a modal opened from a drawer is displayed above it. They join the shared stack
when theme.overlayStack is set on the MantineProvider theme. An inline Modal or Drawer
rendered in the component that calls useModal is displayed below managed modals: render it inside the
modal content, open it with useModal/useDrawer or set theme.overlayStack.
Modal content is rendered inside MantineProvider and does not have access to contexts provided
below it. Render one Modal.Outlet inside your application providers to render managed modals
there. Drawers opened with useDrawer stay in the automatic outlet and are stacked separately from
modals rendered by Modal.Outlet, so a modal opened from a managed drawer may be displayed below it. To keep
them in one stack, render Drawer.Outlet next to Modal.Outlet inside a provider that sets
theme.overlayStack, or do not render outlets:
Shared modal
To open the same modal from different parts of the application, for example, an authentication
modal, call useModal once in a provider component and share the returned object with context.
Modal.Outlet renders all modals opened with useModal: render it once, inside every provider
the modal content uses, including the shared modal context:
Confirm modal
useModal is a building block for application specific modals. The example below creates a
useConfirmModal hook that returns a function resolving to true when the user confirms and to
false when the modal is canceled or closed:
No result yet
Center modal vertically
Remove header
To remove the header, set withCloseButton={false}:
Change size
You can change the modal width by setting the size prop to a predefined size or any valid width, for example, 55% or 50rem.
The Modal width cannot exceed 100vw.
Size auto
Modal with size="auto" will have width that fits its content:
Fullscreen
A fullscreen modal will take the entire screen. It is usually better to change the transition to fade
when the fullScreen prop is set:
Fullscreen on small screens
Set the fullScreenBelow prop to make the modal fullscreen only when the viewport is narrower
than the given breakpoint:
fullScreenBelow accepts a key of theme.breakpoints (xs, sm, md, lg, xl), any CSS length
(for example, '50em' or '800px') or a number of pixels. The modal reacts to viewport changes while
it is opened. The size prop is ignored while the modal is fullscreen. fullScreen takes precedence
over fullScreenBelow – it forces fullscreen at any viewport width.
Customize overlay
Modal uses the Overlay component. You can set any props that Overlay
supports with overlayProps:
Footer
Use the Modal.Footer component to render a footer with actions:
By default, the footer stays pinned to the bottom of the modal while the body scrolls between the header and the footer. When the body content is short, the footer sits at the very bottom with free space above it.
Sticky header and footer
Header and footer stay visible while the body content scrolls. Set stickyHeader={false} or
stickyFooter={false} to make them scroll away with the content:
Both props default to true.
Modal with scroll
Usage with ScrollArea
Change offsets
Use xOffset/yOffset to configure the horizontal/vertical content offsets:
Change transitions
Modal is built with the Transition component. Use the transitionProps
prop to customize any Transition properties:
onExitTransitionEnd and onEnterTransitionEnd
The onExitTransitionEnd and onEnterTransitionEnd props can be used to run code after
the exit/enter transition is finished. For example, this is useful when you want to clear
data after the modal is closed:
Initial focus
Modal uses FocusTrap to trap focus. Add the data-autofocus
attribute to the element that should receive initial focus.
If you do not want to focus any elements when the modal is opened, use the FocusTrap.InitialFocus
component to create a visually hidden element that will receive initial focus:
If you do not add the data-autofocus attribute and do not use FocusTrap.InitialFocus,
the modal will focus the first focusable element inside it, which is usually the close button.
Control behavior
The following props can be used to control Modal behavior.
In most cases, it is not recommended to turn these features off –
it will make the component less accessible.
trapFocus– determines whether focus should be trapped inside the modalcloseOnEscape– determines whether the modal should be closed when theEscapekey is pressedcloseOnClickOutside– determines whether the modal should be closed when the user clicks on the overlayreturnFocus– determines whether focus should be returned to the element that was focused before the modal was opened
Close guard
Use the useModalCloseGuard hook inside modal content to decide whether the user can close the modal.
The guard is called when the close button is clicked, Escape is pressed or the overlay is clicked.
Return false, or a promise that resolves to false, to keep the modal opened.
The hook returns a function that closes the modal through the same guard, use it for Cancel buttons.
modal.close() and the opened prop are not affected by guards:
react-remove-scroll settings
Modal uses the react-remove-scroll
package to lock scroll. You can pass props down to the RemoveScroll component
with removeScrollProps:
Change close icon
Use closeButtonProps to customize the close button:
Compound components
You can use the following compound components to have full control over the Modal rendering:
Modal.Root– context providerModal.Overlay– render OverlayModal.Content– main modal element, should include all modal contentModal.Header– sticky header, usually containsModal.TitleandModal.CloseButtonModal.Title–h2element, thearia-labelledbyofModal.Contentis pointing to this element, usually rendered insideModal.HeaderModal.CloseButton– close button, usually rendered insideModal.HeaderModal.Body– a place for main content, thearia-describedbyofModal.Contentis pointing to this elementModal.Footer– footer element, usually contains action buttons, pinned to the bottom by default (controlled withstickyFooter)
Modal.Stack
Use the Modal.Stack component to render multiple modals at the same time.
Modal.Stack keeps track of opened modals, manages z-index values, focus trapping,
and closeOnEscape behavior. Modal.Stack is designed to be used with the useModalsStack hook.
Differences from using multiple Modal components:
Modal.Stackmanages z-index values – modals that are opened later will always have a higher z-index value regardless of their order in the DOMModal.Stackdisables focus trap andEscapekey handling for all modals except the one that is currently opened- All opened modals stay mounted and visible with a stacked depth effect – modals below the top one are scaled down and offset to create a sense of depth
- Only one overlay is rendered at a time
Modals behind the top one stay above the overlay but cannot be interacted with –
only the top modal receives pointer events, focus and Escape key presses. Set
withStackTransform={false} to disable the stacked depth effect – in this case only the top
modal is visible, modals behind it are hidden until the top one is closed.
Use the maxDepth prop (default 5) to control how many stacked modals are visible behind the
top one at the same time:
Note that Modal.Stack can only be used with the Modal component. Components built with Modal.Root
and other compound components are not compatible with Modal.Stack.
All modals rendered inside Modal.Stack are a part of the stack, stackId prop is required only to
connect modal with the useModalsStack hook. To enable stacking for all modals in your application
without Modal.Stack, see shared stack section.
useModalsStack hook
The useModalsStack hook provides an easy way to control multiple modals at the same time.
It accepts an array of unique modal IDs and returns an object with the following properties:
Example of using useModalsStack with the Modal component:
Shared stack
Set theme.overlayStack to stack all Modal components in your application automatically,
without Modal.Stack wrapper and stackId prop:
With overlayStack enabled, all modals join one shared Modal.Stack. Any modal that is opened
while another modal is opened is rendered on top of it: z-index, focus trap, Escape key handling
and the overlay are managed for the entire application. Drawer components join their
own shared Drawer.Stack – modals and drawers are never stacked visually together, but z-index,
focus trap and Escape key handling always follow the topmost opened modal or drawer. When a
drawer is opened above modals, the modals are dimmed by the overlay together with the page.
overlayStack accepts an object to configure the shared stacks:
When theme.overlayStack is set, Modal.Stack does not create a separate stack – modals
rendered inside it become a part of the shared stack, maxDepth and withStackTransform
props of Modal.Stack are ignored. useModalsStack hook can still be used to manage
opened state of several modals.
stackId values inside the shared stack are scoped per Modal.Stack instance – separate
Modal.Stack components may reuse the same ids (for example, two components that both call
useModalsStack(['first', 'second'])) without conflicts. useModalStackContext called inside such
Modal.Stack returns only the modals of that Modal.Stack, and its close and closeAll
handlers do not affect modals of other Modal.Stack instances.
Use useModalStackContext hook to access the shared stack (or the closest Modal.Stack)
from any component:
useModalStackContext returns an object with the following properties:
Fixed elements offset
The Modal component uses the react-remove-scroll
package to lock scroll. To properly size these elements, add a className to them (documentation):
Accessibility
Use title to name the dialog and closeButtonProps to label its close button: