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

childrenRequired

A single child content element.

Type:React.ReactElement | undefined | null


openRequired

If true, the component is shown.

Type:boolean


rootRefRequired

Type:React.Ref<Element>


aria-hidden

Type:React.AriaAttributes['aria-hidden']


closeAfterTransition

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

Type:boolean

Default:false


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.

Type:PortalProps['container']


disableEscapeKeyDown

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

Type:boolean

Default:false


disableScrollLock

Disable the scroll lock behavior.

Type:boolean

Default:false


onClose

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

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


onKeyDown

Type:React.KeyboardEventHandler


onTransitionEnter

A function called when a transition enters.

Type:() => void


onTransitionExited

A function called when a transition has exited.

Type:() => void


Return value

exited

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

Type:boolean


getBackdropProps

Resolver for the backdrop slot's props.

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


getRootProps

Resolver for the root slot's props.

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


getTransitionProps

Resolver for the transition related props.

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


hasTransition

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

Type:boolean


isTopModal

If true, the modal is the top most one.

Type:() => boolean


portalRef

A ref to the component's portal DOM element.

Type:React.RefCallback<Element> | null


rootRef

A ref to the component's root DOM element.

Type:React.RefCallback<Element> | null