logoAnt Design

⌘ K
  • Design
  • Development
  • Components
  • Blog
  • Resources
5.25.0
  • Components Overview
  • General
    • Button
    • FloatButton
      5.0.0
    • Icon
    • Typography
  • Layout
    • Divider
    • Flex
      5.10.0
    • Grid
    • Layout
    • Space
    • Splitter
      5.21.0
  • Navigation
    • Anchor
    • Breadcrumb
    • Dropdown
    • Menu
    • Pagination
    • Steps
    • Tabs
  • Data Entry
    • AutoComplete
    • Cascader
    • Checkbox
    • ColorPicker
      5.5.0
    • DatePicker
    • Form
    • Input
    • InputNumber
    • Mentions
    • Radio
    • Rate
    • Select
    • Slider
    • Switch
    • TimePicker
    • Transfer
    • TreeSelect
    • Upload
  • Data Display
    • Avatar
    • Badge
    • Calendar
    • Card
    • Carousel
    • Collapse
    • Descriptions
    • Empty
    • Image
    • List
    • Popover
    • QRCode
      5.1.0
    • Segmented
    • Statistic
    • Table
    • Tag
    • Timeline
    • Tooltip
    • Tour
      5.0.0
    • Tree
  • Feedback
    • Alert
    • Drawer
    • Message
    • Modal
    • Notification
    • Popconfirm
    • Progress
    • Result
    • Skeleton
    • Spin
    • Watermark
      5.1.0
  • Other
    • Affix
    • App
      5.1.0
    • ConfigProvider
    • Util
      5.13.0

Modal

Display a modal dialog box, providing a title, content area, and action buttons.
Importimport { Modal } from "antd";
Sourcecomponents/modal
Docs
Edit this pageChangelog

Resources

Ant Design X
Ant Design Charts
Ant Design Pro
Pro Components
Ant Design Mobile
Ant Design Mini
Ant Design Web3
Ant Design Landing-Landing Templates
Scaffolds-Scaffold Market
Umi-React Application Framework
dumi-Component doc generator
qiankun-Micro-Frontends Framework
Ant Motion-Motion Solution
China Mirror 🇨🇳

Community

Awesome Ant Design
Medium
Twitter
yuque logoAnt Design in YuQue
Ant Design in Zhihu
Experience Cloud Blog
seeconf logoSEE Conf-Experience Tech Conference

Help

GitHub
Change Log
FAQ
Bug Report
Issues
Discussions
StackOverflow
SegmentFault

Ant XTech logoMore Products

yuque logoYuQue-Document Collaboration Platform
AntV logoAntV-Data Visualization
Egg logoEgg-Enterprise Node.js Framework
Kitchen logoKitchen-Sketch Toolkit
Galacean logoGalacean-Interactive Graphics Solution
xtech logoAnt Financial Experience Tech
Theme Editor
Made with ❤ by
Ant Group and Ant Design Community
loading

When To Use

When requiring users to interact with the application, but without jumping to a new page and interrupting the user's workflow, you can use Modal to create a new floating layer over the current page to get user feedback or display information.

Additionally, if you need to show a simple confirmation dialog, you can use App.useApp hooks.

Examples

API

Common props ref:Common props

PropertyDescriptionTypeDefaultVersion
afterCloseSpecify a function that will be called when modal is closed completelyfunction-
classNamesConfig Modal build-in module's classNameRecord<SemanticDOM, string>-
stylesConfig Modal build-in module's styleRecord<SemanticDOM, CSSProperties>-5.10.0
cancelButtonPropsThe cancel button propsButtonProps-
cancelTextText of the Cancel buttonReactNodeCancel
centeredCentered Modalbooleanfalse
closableWhether a close (x) button is visible on top right or notboolean | { closeIcon?: React.ReactNode; disabled?: boolean; }true
closeIconCustom close icon. 5.7.0: close button will be hidden when setting to null or falseReactNode<CloseOutlined />
confirmLoadingWhether to apply loading visual effect for OK button or notbooleanfalse
destroyOnCloseWhether to unmount child components on onClosebooleanfalse
destroyOnHiddenWhether to unmount child components on onClosebooleanfalse5.25.0
focusTriggerAfterCloseWhether need to focus trigger element after dialog is closedbooleantrue4.9.0
footerFooter content, set as footer={null} when you don't need default buttonsReactNode | (originNode: ReactNode, extra: { OkBtn: React.FC, CancelBtn: React.FC }) => ReactNode(OK and Cancel buttons)renderFunction: 5.9.0
forceRenderForce render Modalbooleanfalse
getContainerThe mounted node for Modal but still display at fullscreenHTMLElement | () => HTMLElement | Selectors | falsedocument.body
keyboardWhether support press esc to closebooleantrue
maskWhether show mask or notbooleantrue
maskClosableWhether to close the modal dialog when the mask (area outside the modal) is clickedbooleantrue
modalRenderCustom modal content render(node: ReactNode) => ReactNode-4.7.0
okButtonPropsThe ok button propsButtonProps-
okTextText of the OK buttonReactNodeOK
okTypeButton type of the OK buttonstringprimary
styleStyle of floating layer, typically used at least for adjusting the positionCSSProperties-
loadingShow the skeletonboolean5.18.0
titleThe modal dialog's titleReactNode-
openWhether the modal dialog is visible or notbooleanfalse
widthWidth of the modal dialogstring | number | Breakpoint520Breakpoint: 5.23.0
wrapClassNameThe class name of the container of the modal dialogstring-
zIndexThe z-index of the Modalnumber1000
onCancelSpecify a function that will be called when a user clicks mask, close button on top right or Cancel buttonfunction(e)-
onOkSpecify a function that will be called when a user clicks the OK buttonfunction(e)-
afterOpenChangeCallback when the animation ends when Modal is turned on and off(open: boolean) => void-5.4.0

Note

  • The state of Modal will be preserved at it's component lifecycle by default, if you wish to open it with a brand new state every time, set destroyOnHidden on it.
  • There is a situation that using <Modal /> with Form, which won't clear fields value when closing Modal even you have set destroyOnHidden. You need <Form preserve={false} /> in this case.
  • Modal.method() RTL mode only supports hooks.

Modal.method()

There are five ways to display the information based on the content's nature:

  • Modal.info
  • Modal.success
  • Modal.error
  • Modal.warning
  • Modal.confirm

The items listed above are all functions, expecting a settings object as parameter. The properties of the object are follows:

PropertyDescriptionTypeDefaultVersion
afterCloseSpecify a function that will be called when modal is closed completelyfunction-4.9.0
autoFocusButtonSpecify which button to autofocusnull | ok | cancelok
cancelButtonPropsThe cancel button propsButtonProps-
cancelTextText of the Cancel button with Modal.confirmstringCancel
centeredCentered Modalbooleanfalse
classNameThe className of containerstring-
closableWhether a close (x) button is visible on top right of the confirm dialog or notbooleanfalse4.9.0
closeIconCustom close iconReactNodeundefined4.9.0
contentContentReactNode-
footerFooter content, set as footer: null when you don't need default buttonsReactNode | (originNode: ReactNode, extra: { OkBtn: React.FC, CancelBtn: React.FC }) => ReactNode-renderFunction: 5.9.0
getContainerReturn the mount node for ModalHTMLElement | () => HTMLElement | Selectors | falsedocument.body
iconCustom iconReactNode<ExclamationCircleFilled />
keyboardWhether support press esc to closebooleantrue
maskWhether show mask or not.booleantrue
maskClosableWhether to close the modal dialog when the mask (area outside the modal) is clickedbooleanfalse
okButtonPropsThe ok button propsButtonProps-
okTextText of the OK buttonstringOK
okTypeButton type of the OK buttonstringprimary
styleStyle of floating layer, typically used at least for adjusting the positionCSSProperties-
titleTitleReactNode-
widthWidth of the modal dialogstring | number416
wrapClassNameThe class name of the container of the modal dialogstring-4.18.0
zIndexThe z-index of the Modalnumber1000
onCancelClick to onCancel the callback, the parameter is the closing function, if it returns a promise, resolve means normal closing, reject means not closingfunction(close)-
onOkClick to onOk the callback, the parameter is the closing function, if it returns a promise, resolve means normal closing, reject means not closingfunction(close)-

All the Modal.methods will return a reference, and then we can update and close the modal dialog by the reference.

jsx
const modal = Modal.info();
modal.update({
title: 'Updated title',
content: 'Updated content',
});
// on 4.8.0 or above, you can pass a function to update modal
modal.update((prevConfig) => ({
...prevConfig,
title: `${prevConfig.title} (New)`,
}));
modal.destroy();
  • Modal.destroyAll

Modal.destroyAll() could destroy all confirmation modal dialogs(Modal.confirm|success|info|error|warning). Usually, you can use it in router change event to destroy confirm modal dialog automatically without use modal reference to close( it's too complex to use for all modal dialogs)

jsx
import { browserHistory } from 'react-router';
// router change
browserHistory.listen(() => {
Modal.destroyAll();
});

Modal.useModal()

When you need using Context, you can use contextHolder which created by Modal.useModal to insert into children. Modal created by hooks will get all the context where contextHolder are. Created modal has the same creating function with Modal.method.

jsx
const [modal, contextHolder] = Modal.useModal();
React.useEffect(() => {
modal.confirm({
// ...
});
}, []);
return <div>{contextHolder}</div>;

modal.confirm return method:

  • destroy: Destroy current modal
  • update: Update current modal
  • then: (Hooks only) Promise chain call, support await operation
tsx
// Return `true` when click `onOk` and `false` when click `onCancel`
const confirmed = await modal.confirm({ ... });

Semantic DOM

Design Token

Component TokenHow to use?
Token NameDescriptionTypeDefault Value
contentBgBackground color of contentstring#ffffff
footerBgBackground color of footerstringtransparent
headerBgBackground color of headerstring#ffffff
titleColorFont color of titlestringrgba(0,0,0,0.88)
titleFontSizeFont size of titlenumber16
titleLineHeightLine height of titlestring | number1.5
Global TokenHow to use?

FAQ

Why content not update when Modal closed?

Modal will use memo to avoid content jumping when closed. Also, if you use Form in Modal, you can reset initialValues by calling resetFields in effect.

Why I can not access context, redux, ConfigProvider locale/prefixCls in Modal.xxx?

antd will dynamic create React instance by ReactDOM.render when call Modal methods. Whose context is different with origin code located context.

When you need context info (like ConfigProvider context), you can use Modal.useModal to get modal instance and contextHolder node. And put it in your children:

tsx
const [modal, contextHolder] = Modal.useModal();
// then call modal.confirm instead of Modal.confirm
return (
<Context1.Provider value="Ant">
{/* contextHolder is in Context1, which means modal will get context of Context1 */}
{contextHolder}
<Context2.Provider value="Design">
{/* contextHolder is out of Context2, which means modal will not get context of Context2 */}
</Context2.Provider>
</Context1.Provider>
);

Note: You must insert contextHolder into your children with hooks. You can use origin method if you do not need context connection.

App Package Component can be used to simplify the problem of useModal and other methods that need to manually implant contextHolder.

How to set static methods prefixCls ?

You can config with ConfigProvider.config

Basic

Basic modal.

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Customized Footer

A more complex example which define a customized footer button bar. The dialog will change to loading state after clicking the submit button, and when the loading is done, the modal dialog will be closed.

You could set footer to null if you don't need default footer buttons.

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Customized Footer render function

Customize the footer rendering function to support extensions on top of the original.

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
5.9.0
Internationalization

To customize the text of the buttons, you need to set okText and cancelText props.

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
To customize the position of modal

You can use centered,style.top or other styles to set position of modal dialog.

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Custom modal content render

Custom modal content render. use react-draggable implements draggable.

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Static Method

In most case, you do not need static method. It can not consume context like dynamic theme. Please use hooks version or App provided instance first.

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Customize className for build-in module

Set the className of the build-in module (header, body, footer, mask, wrapper) of the modal through the classNames property.

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Asynchronously close

Asynchronously close a modal dialog when the OK button is pressed. For example, you can use this pattern when you submit a form.

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Loading

Set the loading status of Modal.

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
5.18.0
Use hooks to get context

Use Modal.useModal to get contextHolder with context accessible issue. Only hooks method support Promise await operation.

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Manual to update destroy

Manually updating and destroying a modal through instance.

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Customize footer buttons props

Passing okButtonProps and cancelButtonProps will customize the OK button and cancel button props.

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
To customize the width of modal

Use width to set the width of the modal dialog.

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Static confirmation

Use confirm() to show a confirmation modal dialog. Let onCancel/onOk function return a promise object to delay closing the dialog.

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
destroy confirmation modal dialog

Modal.destroyAll() will destroy all confirmation modal dialogs. Usually, you can use it in router change event to destroy confirm modal dialog automatically.

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code


  • mask
    5.13.0
    Mask element
  • content
    5.13.0
    Modal container element
  • wrapper
    5.13.0
    Wrapper element. Used for motion container
  • header
    5.13.0
    Header element
  • body
    5.13.0
    Body element
  • footer
    5.13.0
    Footer element