Modal

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

<code src="./demo/basic.tsx">Basic</code> <code src="./demo/async.tsx">Asynchronously close</code> <code src="./demo/footer.tsx">Customized Footer</code> <code src="./demo/mask.tsx">mask</code> <code src="./demo/loading.tsx" version="5.18.0">Loading</code> <code src="./demo/footer-render.tsx" version="5.9.0">Customized Footer render function</code> <code src="./demo/hooks.tsx">Use hooks to get context</code> <code src="./demo/locale.tsx">Internationalization</code> <code src="./demo/manual.tsx">Manual to update destroy</code> <code src="./demo/position.tsx">To customize the position of modal</code> <code src="./demo/dark.tsx" debug>Demo for debugging</code> <code src="./demo/button-props.tsx">Customize footer buttons props</code> <code src="./demo/modal-render.tsx">Custom modal content render</code> <code src="./demo/width.tsx">To customize the width of modal</code> <code src="./demo/static-info.tsx">Static Method</code> <code src="./demo/confirm.tsx">Static confirmation</code> <code src="./demo/confirm-router.tsx">destroy confirmation modal dialog</code> <code src="./demo/style-class.tsx" version="6.0.0">Custom semantic dom styling</code> <code src="./demo/nested.tsx" debug>Nested Modal</code> <code src="./demo/render-panel.tsx" debug>_InternalPanelDoNotUseOrYouWillBeFired</code> <code src="./demo/custom-mouse-position.tsx" debug>Control modal's animation origin position</code> <code src="./demo/wireframe.tsx" debug>Wireframe</code> <code src="./demo/component-token.tsx" debug>Component Token</code>

API

Common props ref：Common props

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:

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

ClosableType

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)

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.

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

// Return `true` when click `onOk` and `false` when click `onCancel`
const confirmed = await modal.confirm({ ... });

Semantic DOM

<code src="./demo/_semantic.tsx" simplify="true"></code>

Design Token

<ComponentTokenTable component="Modal"></ComponentTokenTable>

FAQ

Why content not update when Modal closed? {#faq-content-not-update}

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? {#faq-context-redux}

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:

const [modal, contextHolder] = Modal.useModal();

// then call modal.confirm instead of Modal.confirm

return (
  <Context1.Provider value="Ant">
    {contextHolder}
    <Context2.Provider value="Design">
    </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 ？ {#faq-set-prefix-cls}

You can config with ConfigProvider.config