Show · Modal
Modal
Modals are used to wait for the user to interact, inform the user of important information, or display more information without losing context.
Demos
How to import
Basic Usage
Mask Closable
You can set
maskClosable={false}
to prevent modal from closing when clicking on the mask.Custom Button Text
You can set button text using
okText
and cancelText
.In the case of creating a modal with static methods, you will have to use these two properties to set i18 texts at this moment. Because we cannot modify the React component tree, imperatively inserted components cannot consume Locale-related Context
Custom Button Properties
You can set button properties using
okButtonProps
and cancelButtonProps
.Custom Header & Footer
For more customized modal, you could use
header
and footer
. Set header={null}
if you do not want header area, or footer={null}
to remove footer area including buttons.Custom Style
You can use
style
to customize styling or position e.g. style.top = '30vh'
, or use centered
to center modal. Also, you could use maskStyle
to customize mask style or bodyStyle
for content style.Custom Modal
By using
header
, footer
, etc, you could create any modal to your needs.Full Screen Modal
set
fullScreen={true}
can use full screen ModalConfirm Modal
You could use static methods to create a confirm Modal. Use
icon
to customize icon.useModal Hooks
You could use
Modal.useModal
to create a contextHolder
that could access context.API Reference
Modal
Properties | Instructions | type | Default |
---|---|---|---|
afterClose | Callback function when modal closed completely >= v1.16.0 | () => void | - |
bodyStyle | Content style | CSSProperties | - |
cancelButtonProps | Properties for cancel button | ButtonProps | - |
cancelText | Text for cancel button | string | - |
centered | Toggle whether to center modal | boolean | false |
closable | Toggle whether to show close button | boolean | true |
closeIcon | Icon for close button >= v1.0.0 | ReactNode | <IconClose /> |
closeOnEsc | Toggle whether to allow close modal by keyboard event Esc >= v1.0.0 | boolean | true |
confirmLoading | Toggle loading state of confirm button | boolean | false |
content | Content | ReactNode | - |
footer | Footer | ReactNode | - |
fullScreen | Is modal FullScreen(will override width and height) >= v1.18.0 | boolean | false |
getPopupContainer | Specifies the parent DOM, and the bullet layer will be rendered to the DOM, you need to set 'position: relative` This will change the DOM tree position, but not the view's rendering position. >= v0.33.0 | () => HTMLElement | () => document.body |
hasCancel | Toggle whether to show cancal button | boolean | true |
header | Header | ReactNode | - |
height | Height | number | - |
icon | Custom icon v1.1.0 | ReactNode | - |
keepDOM | Keep dom tree when close modal >= v1.0.0 | boolean | false |
lazyRender | Lazy render modal, used with keepDOM >=v1.0.0 | boolean | true |
mask | Toggle whether to show mask | boolean | true |
maskClosable | Toggle whether to allow closing when clicking mask | boolean | true |
maskStyle | Mask style | CSSProperties | - |
motion | animation switch | boolean | true |
okButtonProps | Properties for confirm button | ButtonProps | - |
okText | Text for confirm button | string | - |
okType | Type for confirm button, optional: 'primary'、'secondary'、'tertiary'、'warning'、'danger' | string | primary |
preventScroll | Indicates whether the browser should scroll the document to display the newly focused element, acting on the focus method inside the component, excluding the component passed in by the user | boolean | |
size | Size of modal, one of small (448px), medium (684px), large (920px), full-width (100vw - 64px) >= v1.0.0 | string | 'small' |
style | Inline style | CSSProperties | - |
title | Title | ReactNode | - |
visible | Toggle visibility of the modal | boolean | false |
width | Width | number | 448 |
zIndex | Z-index value for mask | number | 1000 |
onCancel | Callback function when clicking cancel button | (e: any) => void | Promise<any> | - |
onOk | Callback function when clicking confirm button | (e: any) => void | Promise<any> | - |
Static Method
Modal.info
Modal.success
Modal.error
Modal.warning
Modal.confirm
Properties | Instructions | type | Default |
---|---|---|---|
bodyStyle | Content style | CSSProperties | - |
cancelButtonProps | Properties for cancel button | ButtonProps | - |
cancelText | Text for cancel button | string | - |
centered | Toggle whether to center modal | boolean | false |
closable | Toggle whether to show close button | boolean | true |
content | Content | ReactNode | - |
confirmLoading | Toggle loading state of confirm button | boolean | false |
footer | Footer | ReactNode | - |
header | Header | ReactNode | - |
height | Height | number | - |
icon | Customized icon | ReactNode | - |
mask | Toggle whether to show mask | boolean | true |
maskClosable | Toggle whether to allow closing when clicking mask | boolean | true |
maskStyle | Mask style | CSSProperties | - |
okButtonProps | Properties for confirm button | ButtonProps | - |
okText | Text for confirm button | string | - |
okType | Type for confirm button | string | primary |
size | Size of modal, one of small (448px), medium (684px), large (920px), full-width (100vw - 64px) v >= 0.33.0 | string | 'small' |
style | Inline style | CSSProperties | - |
title | Title | ReactNode | - |
width | Width | number | 520 |
zIndex | Z-index value for mask | number | 1000 |
onCancel | Callback function when clicking cancel button | (e: any) => void | Promise<any> | - |
onOk | Callback function when clicking confirm button | (e: any) => void | Promise<any> | - |
Creating modal with the above methods will return a reference to the instance. You could use it to update or close the modal.|
Modal.destroyAll
v>=0.37.0
You could use Modal.destroyAll() to destroy Modal that created by methods above e.g.
.info()
Modal.useModal
v>=1.2.0
When you need access Context, you could useModal.useModal
to create acontextHolder
and insert to corresponding DOM tree. Modal created by hooks will be able to access the context wherecontextHolder
is inserted. Hook modal shares the same methods with Modal.method.
Accessibility
ARIA
- Modal role set to
dialog
- aria-modal is set to true
- aria-labelledby corresponds to Modal header
- aria-describedby corresponds to Modal body
Keyboard and focus
- Modal automatically gets the focus when it is popped up, and when it is closed, the focus automatically returns to the element before it was opened.
- Keyboard users can use the
Tab
key andShift + Tab
to move the focus within the Modal, including the Modal's own close button and OK cancel button. At this time, the elements behind the Modal cannot be tab-focused. - When Modal is opened, the focus is on the cancel button by default, which can be controlled by passing autoFocus in cancelButtonProps or okButtonProps.
- By adding autoFocus to the form element that needs to be focused in the Modal content, the Modal can automatically focus on the element when it is opened (the autoFocus of cancelButtonProps needs to be set to false at the same time).
- Modify the default value of closeOnEsc to true, allowing users to directly close Modal through the keyboard for a better experience
Content Guidelines
- Imperative Modal and Default Modal The title of the two modal dialogs uses the format of verb + noun, whether it is a declarative sentence or a question sentence
✅ Recommended usage | ❌ Deprecated usage |
---|---|
Edit ticket | Edit |
Delete form? | Are you sure you want to delete form? |
- The operation buttons of the two modal dialog boxes only need to use the verbs in the title under the premise of ensuring that the title description is clear
✅ Recommended usage | ❌ Deprecated usage |
---|---|
Edit | Edit ticket |
- Text specification for imperative Modal
- Give a specific explanation to the title, do not repeat the information of the title
- Make sure users know how to act if necessary
Design Tokens
FAQ
Why the button texts in Modal.confirm are not internationalized even when I use LocaleProvider?
In version >= 1.2.0, you could useModal.useModal
to create acontextHolder
that is accessible to config from ConfigProvider or LocaleProvider.For version before 1.2 or if you don't want to use Hooks, you could also useokText
andcancelText
to set i18 texts at this moment.Why is the spacing between title and content different under imperative and non-imperative calls?
In the imperative call scenario, the title and content are more closely related, so expressing this strong correlation with a closer distance is in line with expectations. If users don't want this effect, they can do their own style overrides.