Modal

Default

Loading preview

Imperative

Loading preview

Raw Modal

Loading preview

APIs

Modal

DeprecatedUse `Modal` from `@lobehub/ui/base-ui` instead.

Modal properties

afterCloseModalProps

() => void

afterOpenChangeModalProps

(open: boolean) => void

Callback when the animation ends when Modal is turned on and off

allowFullscreen

boolean

bodyProps

any

bodyStyleDeprecatedModalProps

React.CSSProperties

Please use `styles.body` instead

cancelButtonPropsModalProps

ButtonProps

cancelTextModalProps

null | string | number | bigint | false | true | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | React.ReactPortal | Promise<AwaitedReactNode>

Text of the Cancel button

centeredModalProps

boolean

Centered Modal

childrenModalProps

null | string | number | bigint | false | true | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | React.ReactPortal | Promise<AwaitedReactNode>

classNameModalProps

string

classNamesModalCommonProps

(info: { props: ModalProps; }) => DeepClassNameType<{ root?: string; header?: string; body?: string; footer?: string; container?: string; title?: string; wrapper?: string; mask?: string; close?: string; } | undefined> | DeepClassNameType<{ root?: string; header?: string; body?: string; footer?: string; container?: string; title?: string; wrapper?: string; mask?: string; close?: string; }>

closableModalCommonProps

false | true | ClosableType & React.AriaAttributes & { onClose?: () => void; afterClose?: () => void; }

closeIconModalProps

null | string | number | bigint | false | true | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | React.ReactPortal | Promise<AwaitedReactNode>

confirmLoadingModalProps

boolean

Whether to apply loading visual effect for OK button or not

destroyOnCloseDeprecatedModalProps

boolean

Please use `destroyOnHidden` instead

destroyOnHiddenSince 5.25.0ModalProps

boolean

enableResponsive

boolean

Defaults to true.

focusableModalProps

FocusableConfig

focusTriggerAfterCloseDeprecatedModalProps

boolean

Please use `focusable.focusTriggerAfterClose` instead

footerModalCommonProps

null | string | number | bigint | false | true | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | React.ReactPortal | Promise<AwaitedReactNode> | (originNode: React.ReactNode, extra: { OkBtn: React.FC; CancelBtn: React.FC; }) => React.ReactNode

forceRenderModalProps

boolean

Force render Modal

getContainerModalProps

string | false | HTMLElement | getContainerFunc

height

string | number

Defaults to "75dvh".

keyboardModalProps

boolean

loadingSince 5.18.0ModalProps

boolean

maskModalProps

false | true | MaskConfig

maskClosableDeprecatedModalProps

boolean

Please use `mask.closable` instead

maskProps

any

maskStyleDeprecatedModalProps

React.CSSProperties

Please use `styles.mask` instead

maskTransitionNameModalProps

string

modalRenderModalProps

(node: React.ReactNode) => React.ReactNode

mousePositionModalProps

null | { x: number; y: number; }

okButtonPropsModalProps

ButtonProps

okTextModalProps

null | string | number | bigint | false | true | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | React.ReactPortal | Promise<AwaitedReactNode>

Text of the OK button

onCancelModalProps

(e: React.MouseEvent<HTMLButtonElement> | React.KeyboardEvent<HTMLElement>) => void

Specify a function that will be called when a user clicks mask, close button on top right or Cancel button, or presses Esc key

onOkModalProps

(e: React.MouseEvent<HTMLButtonElement>) => void

Specify a function that will be called when a user clicks the OK button

openModalProps

boolean

Whether the modal dialog is visible or not

paddings

{ desktop?: number; mobile?: number; }

panelRef

null | (instance: HTMLDivElement | null) => void | (() => VoidOrUndefinedOnly) | DO_NOT_USE_OR_YOU_WILL_BE_FIRED_CALLBACK_REF_RETURN_VALUES[keyof DO_NOT_USE_OR_YOU_WILL_BE_FIRED_CALLBACK_REF_RETURN_VALUES] | RefObject<HTMLDivElement | null>

prefixClsModalProps

string

rootClassNameModalProps

string

rootStyleModalProps

React.CSSProperties

scrollLockModalProps

boolean

Control whether to lock body scroll when modal opens. Default is true.

styleModalProps

React.CSSProperties

stylesModalCommonProps

(info: { props: ModalProps; }) => DeepStylesType<{ root?: React.CSSProperties; header?: React.CSSProperties; body?: React.CSSProperties; footer?: React.CSSProperties; container?: React.CSSProperties; title?: React.CSSProperties; wrapper?: React.CSSProperties; mask?: React.CSSProperties; close?: React.CSSProperties; } | undefined> | DeepStylesType<{ root?: React.CSSProperties; header?: React.CSSProperties; body?: React.CSSProperties; footer?: React.CSSProperties; container?: React.CSSProperties; title?: React.CSSProperties; wrapper?: React.CSSProperties; mask?: React.CSSProperties; close?: React.CSSProperties; }>

titleModalProps

null | string | number | bigint | false | true | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | React.ReactPortal | Promise<AwaitedReactNode>

The modal dialog's title

Defaults to " ".

transitionNameModalProps

string

visible

boolean

widthModalProps

string | number | Partial<Record<'xxxl' | 'xxl' | 'xl' | 'lg' | 'md' | 'sm' | 'xs', string | number>>

Width of the modal dialog

Defaults to 700.

wrapPropsModalProps

any

wrapStyle

Record<string, any>

zIndexModalProps

number

Modal inherits most properties from Ant Design's Modal component, except for 'okType' and 'wrapClassName'. When displayed on mobile screens (when enableResponsive is true), it automatically switches to a Drawer component with a bottom placement.

Responsive Behavior

On desktop screens, the component renders as a traditional modal dialog. On mobile screens, it transforms into a bottom drawer for better mobile user experience. The responsiveness is handled automatically, but can be disabled by setting enableResponsive to false.

createModal

createModal provides an imperative way to open a modal. It accepts ImperativeModalProps and returns a controller instance. Make sure to render ModalHost once in your app (usually near the root) so the modal can portal into the document.

Name	Description	Type
close	Close the modal	() => void
update	Update modal props	(next) => void
destroy	Destroy the modal immediately	() => void
setCanDismissByClickOutside	Toggle mask click dismiss	(value: boolean) => void

ModalHost is a lightweight portal target for imperative modals.

Property	Description	Type	Default
root	Custom portal root element	HTMLElement | ShadowRoot	body

ImperativeModalProps extends ModalProps.

createRawModal

createRawModal is for existing modal components that already manage their own <Modal />. It injects open and onClose automatically (or the remapped keys), so you only pass the remaining props.

createRawModal(ModalComponent, props, options?)

It still requires rendering ModalHost once in your app.

If your modal uses different prop names (e.g. visible/onCancel), pass both openKey and onCloseKey.

Option	Description	Type	Default
destroyOnClose	Destroy modal after calling onClose	boolean	true
destroyDelay	Delay before destroy (for close animation)	number	200
openKey	Prop name for open state	string	'open'
onCloseKey	Prop name for close handler	string	'onClose'

RawModalComponentProps defines the default required props for the component (when not remapping):

Property	Description	Type
open	Open state	boolean
onClose	Close handler	() => void

useModalContext

Inside the imperative modal content, you can access modal actions via useModalContext.

Name	Description	Type
close	Close the modal	() => void
setCanDismissByClickOutside	Toggle mask click dismiss	(value: boolean) => void

ModalProvider

ModalProvider lets you pass modal actions to descendants declaratively (it is used internally by imperative modals).

Property	Description	Type	Default
value	Modal actions context value	{ close: () => void; setCanDismissByClickOutside: (value: boolean) => void }	-