Skip to content
+

Modal

The Modal component lets you create dialogs, popovers, lightboxes, and other elements that force the user to take action before continuing.

useModal API

Import

import { unstable_useModal as useModal } from '@mui/base/unstable_useModal';
// or
import { unstable_useModal as useModal } from '@mui/base';
Learn about the difference by reading this guide on minimizing bundle size.

Parameters

NameTypeDefaultDescription
children*React.ReactElement | undefined | null-

A single child content element.

open*boolean-

If true, the component is shown.

rootRef*React.Ref<Element>-
aria-hiddenReact.AriaAttributes['aria-hidden']-
closeAfterTransitionbooleanfalse

When set to true the Modal waits until a nested Transition is completed before closing.

containerPortalProps['container']-

An HTML element or function that returns one. The container will have the portal children appended to it.
You can also provide a callback, which is called in a React layout effect. This lets you set the container from a ref, and also makes server-side rendering possible.
By default, it uses the body of the top-level document object, so it's simply document.body most of the time.

disableEscapeKeyDownbooleanfalse

If true, hitting escape will not fire the onClose callback.

disableScrollLockbooleanfalse

Disable the scroll lock behavior.

onClose{ bivarianceHack(event: {}, reason: 'backdropClick' | 'escapeKeyDown'): void }['bivarianceHack']-

Callback fired when the component requests to be closed. The reason parameter can optionally be used to control the response to onClose.

onKeyDownReact.KeyboardEventHandler-
onTransitionEnter() => void-

A function called when a transition enters.

onTransitionExited() => void-

A function called when a transition has exited.

Return value

NameTypeDescription
exitedboolean

If true, the exiting transition finished (to be used for unmounting the component).

getBackdropProps<TOther extends EventHandlers = {}>(externalProps?: TOther) => UseModalBackdropSlotProps<TOther>

Resolver for the backdrop slot's props.

getRootProps<TOther extends EventHandlers = {}>(externalProps?: TOther) => UseModalRootSlotProps<TOther>

Resolver for the root slot's props.

getTransitionProps<TOther extends EventHandlers = {}>(externalProps?: TOther) => { onEnter: () => void; onExited: () => void }

Resolver for the transition related props.

hasTransitionboolean

If true, the component's child is transition component.

isTopModal() => boolean

If true, the modal is the top most one.

portalRefReact.RefCallback<Element> | null

A ref to the component's portal DOM element.

rootRefReact.RefCallback<Element> | null

A ref to the component's root DOM element.