- Components Overview
- Changelogv5.28.1
- General
- Layout
- Navigation
- Data Entry
- Data Display
- Feedback
- Other
When requiring users to interact with the application, but without jumping to a new page and interrupting the user's workflow, you can useModal 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 useApp.useApp hooks.
Common props ref：Common props
| Property | Description | Type | Default | Version |
|---|---|---|---|---|
| afterClose | Specify a function that will be called when modal is closed completely | function | - | |
| classNames | Config Modal build-in module's className | Record<SemanticDOM, string> | - | |
| styles | Config Modal build-in module's style | Record<SemanticDOM, CSSProperties> | - | 5.10.0 |
| cancelButtonProps | The cancel button props | ButtonProps | - | |
| cancelText | Text of the Cancel button | ReactNode | Cancel | |
| centered | Centered Modal | boolean | false | |
| closable | Whether a close (x) button is visible on top right or not | boolean | { closeIcon?: React.ReactNode; disabled?: boolean; } | true | |
| closeIcon | Custom close icon. 5.7.0: close button will be hidden when setting tonull orfalse | ReactNode | <CloseOutlined /> | |
| confirmLoading | Whether to apply loading visual effect for OK button or not | boolean | false | |
| Whether to unmount child components on onClose | boolean | false | ||
| destroyOnHidden | Whether to unmount child components on onClose | boolean | false | 5.25.0 |
| focusTriggerAfterClose | Whether need to focus trigger element after dialog is closed | boolean | true | 4.9.0 |
| footer | Footer content, set asfooter={null} when you don't need default buttons | ReactNode | (originNode: ReactNode, extra: { OkBtn: React.FC, CancelBtn: React.FC }) => ReactNode | (OK and Cancel buttons) | renderFunction: 5.9.0 |
| forceRender | Force render Modal | boolean | false | |
| getContainer | The mounted node for Modal but still display at fullscreen | HTMLElement | () => HTMLElement | Selectors | false | document.body | |
| keyboard | Whether support press esc to close | boolean | true | |
| mask | Whether show mask or not | boolean | true | |
| maskClosable | Whether to close the modal dialog when the mask (area outside the modal) is clicked | boolean | true | |
| modalRender | Custom modal content render | (node: ReactNode) => ReactNode | - | 4.7.0 |
| okButtonProps | The ok button props | ButtonProps | - | |
| okText | Text of the OK button | ReactNode | OK | |
| okType | Buttontype of the OK button | string | primary | |
| style | Style of floating layer, typically used at least for adjusting the position | CSSProperties | - | |
| loading | Show the skeleton | boolean | 5.18.0 | |
| title | The modal dialog's title | ReactNode | - | |
| open | Whether the modal dialog is visible or not | boolean | false | |
| width | Width of the modal dialog | string | number |Breakpoint | 520 | Breakpoint: 5.23.0 |
| wrapClassName | The class name of the container of the modal dialog | string | - | |
| zIndex | Thez-index of the Modal | number | 1000 | |
| onCancel | Specify a function that will be called when a user clicks mask, close button on top right or Cancel button | function(e) | - | |
| onOk | Specify a function that will be called when a user clicks the OK button | function(e) | - | |
| afterOpenChange | Callback when the animation ends when Modal is turned on and off | (open: boolean) => void | - | 5.4.0 |
destroyOnHidden on it.<Modal /> with Form, which won't clear fields value when closing Modal even you have setdestroyOnHidden. You need<Form preserve={false} /> in this case.Modal.method() RTL mode only supports hooks.There are five ways to display the information based on the content's nature:
Modal.infoModal.successModal.errorModal.warningModal.confirmThe items listed above are all functions, expecting a settings object as parameter. The properties of the object are follows:
| Property | Description | Type | Default | Version |
|---|---|---|---|---|
| afterClose | Specify a function that will be called when modal is closed completely | function | - | 4.9.0 |
| autoFocusButton | Specify which button to autofocus | null |ok |cancel | ok | |
| cancelButtonProps | The cancel button props | ButtonProps | - | |
| cancelText | Text of the Cancel button with Modal.confirm | string | Cancel | |
| centered | Centered Modal | boolean | false | |
| className | The className of container | string | - | |
| closable | Whether a close (x) button is visible on top right of the confirm dialog or not | boolean | false | 4.9.0 |
| closeIcon | Custom close icon | ReactNode | undefined | 4.9.0 |
| content | Content | ReactNode | - | |
| footer | Footer content, set asfooter: null when you don't need default buttons | ReactNode | (originNode: ReactNode, extra: { OkBtn: React.FC, CancelBtn: React.FC }) => ReactNode | - | renderFunction: 5.9.0 |
| getContainer | Return the mount node for Modal | HTMLElement | () => HTMLElement | Selectors | false | document.body | |
| icon | Custom icon | ReactNode | <ExclamationCircleFilled /> | |
| keyboard | Whether support press esc to close | boolean | true | |
| mask | Whether show mask or not. | boolean | true | |
| maskClosable | Whether to close the modal dialog when the mask (area outside the modal) is clicked | boolean | false | |
| okButtonProps | The ok button props | ButtonProps | - | |
| okText | Text of the OK button | string | OK | |
| okType | Buttontype of the OK button | string | primary | |
| style | Style of floating layer, typically used at least for adjusting the position | CSSProperties | - | |
| title | Title | ReactNode | - | |
| width | Width of the modal dialog | string | number | 416 | |
| wrapClassName | The class name of the container of the modal dialog | string | - | 4.18.0 |
| zIndex | Thez-index of the Modal | number | 1000 | |
| onCancel | Click to onCancel the callback, the parameter is the closing function, if it returns a promise, resolve means normal closing, reject means not closing | function(close) | - | |
| onOk | Click to onOk the callback, the parameter is the closing function, if it returns a promise, resolve means normal closing, reject means not closing | function(close) | - |
All theModal.methods will return a reference, and then we can update and close the modal dialog by the reference.
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 modalmodal.update((prevConfig)=>({...prevConfig,title:`${prevConfig.title} (New)`,}));modal.destroy();
Modal.destroyAllModal.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)
import{ browserHistory}from'react-router';// router changebrowserHistory.listen(()=>{Modal.destroyAll();});
When you need using Context, you can usecontextHolder which created byModal.useModal to insert into children. Modal created by hooks will get all the context wherecontextHolder are. Createdmodal has the same creating function withModal.method.
const[modal, contextHolder]=Modal.useModal();React.useEffect(()=>{modal.confirm({// ...});},[]);return<div>{contextHolder}</div>;
modal.confirm return method:
destroy: Destroy current modalupdate: Update current modalthen: (Hooks only) Promise chain call, supportawait operation// Return `true` when click `onOk` and `false` when click `onCancel`const confirmed=await modal.confirm({...});
| Token Name | Description | Type | Default Value |
|---|---|---|---|
| contentBg | Background color of content | string | #ffffff |
| footerBg | Background color of footer | string | transparent |
| headerBg | Background color of header | string | #ffffff |
| titleColor | Font color of title | string | rgba(0,0,0,0.88) |
| titleFontSize | Font size of title | number | 16 |
| titleLineHeight | Line height of title | string | number | 1.5 |
Modal will use memo to avoid content jumping when closed. Also, if you use Form in Modal, you can resetinitialValues by callingresetFields in effect.
locale/prefixCls in Modal.xxx?antd will dynamic create React instance byReactDOM.render when call Modal methods. Whose context is different with origin code located context.
When you need context info (like ConfigProvider context), you can useModal.useModal to getmodal instance andcontextHolder node. And put it in your children:
const[modal, contextHolder]=Modal.useModal();// then call modal.confirm instead of Modal.confirmreturn(<Context1.Providervalue="Ant">{/* contextHolder is in Context1, which means modal will get context of Context1 */}{contextHolder}<Context2.Providervalue="Design">{/* contextHolder is out of Context2, which means modal will not get context of Context2 */}</Context2.Provider></Context1.Provider>);
Note: You must insertcontextHolder 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
useModaland other methods that need to manually implant contextHolder.
You can config withConfigProvider.config
Basic modal.
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 setfooter tonull if you don't need default footer buttons.
Customize the footer rendering function to support extensions on top of the original.
To customize the text of the buttons, you need to setokText andcancelText props.
You can usecentered,style.top or other styles to set position of modal dialog.
Custom modal content render. usereact-draggable implements draggable.
Static methods cannot consume Context provided byConfigProvider. When enablelayer, they may also cause style errors. Please use hooks version orApp provided instance first.
Set the className of the build-in module (header, body, footer, mask, wrapper) of the modal through the classNames property.
Asynchronously close a modal dialog when the OK button is pressed. For example, you can use this pattern when you submit a form.
Set the loading status of Modal.
UseModal.useModal to getcontextHolder with context accessible issue. Only hooks method support Promiseawait operation.
Manually updating and destroying a modal through instance.
PassingokButtonProps andcancelButtonProps will customize the OK button and cancel button props.
Usewidth to set the width of the modal dialog.
Useconfirm() to show a confirmation modal dialog. Let onCancel/onOk function return a promise object to delay closing the dialog.
Modal.destroyAll() will destroy all confirmation modal dialogs. Usually, you can use it in router change event to destroy confirm modal dialog automatically.