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.
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 Modal

Confirm 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

PropertiesInstructionstypeDefault
afterCloseCallback function when modal closed completely
>= v1.16.0
() => void-
bodyStyleContent styleCSSProperties-
cancelButtonPropsProperties for cancel buttonButtonProps-
cancelTextText for cancel buttonstring-
centeredToggle whether to center modalbooleanfalse
closableToggle whether to show close buttonbooleantrue
closeIconIcon for close button
>= v1.0.0
ReactNode<IconClose />
closeOnEscToggle whether to allow close modal by keyboard event Esc
>= v1.0.0
booleantrue
confirmLoadingToggle loading state of confirm buttonbooleanfalse
contentContentReactNode-
footerFooterReactNode-
fullScreenIs modal FullScreen(will override width and height)
>= v1.18.0
booleanfalse
getPopupContainerSpecifies the parent DOM, and the bullet layer will be rendered to the DOM, you need to set 'position: relative`
>= v0.33.0
() => HTMLElement() => document.body
hasCancelToggle whether to show cancal buttonbooleantrue
headerHeaderReactNode-
heightHeightnumber-
iconCustom icon
v1.1.0
ReactNode-
keepDOMKeep dom tree when close modal
>= v1.0.0
booleanfalse
lazyRenderLazy render modal, used with keepDOM
>=v1.0.0
booleantrue
maskToggle whether to show maskbooleantrue
maskClosableToggle whether to allow closing when clicking maskbooleantrue
maskStyleMask styleCSSProperties-
motionanimation switchbooleantrue
okButtonPropsProperties for confirm buttonButtonProps-
okTextText for confirm buttonstring-
okTypeType for confirm button, optional: 'primary'、'secondary'、'tertiary'、'warning'、'danger'stringprimary
preventScrollIndicates 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 userboolean
sizeSize of modal, one of small(448px), medium(684px), large(920px), full-width(100vw - 64px)
>= v1.0.0
string'small'
styleInline styleCSSProperties-
titleTitleReactNode-
visibleToggle visibility of the modalbooleanfalse
widthWidthnumber448
zIndexZ-index value for masknumber1000
onCancelCallback function when clicking cancel button(e: any) => void | Promise<any>-
onOkCallback function when clicking confirm button(e: any) => void | Promise<any>-

Static Method

  • Modal.info
  • Modal.success
  • Modal.error
  • Modal.warning
  • Modal.confirm
PropertiesInstructionstypeDefault
bodyStyleContent styleCSSProperties-
cancelButtonPropsProperties for cancel buttonButtonProps-
cancelTextText for cancel buttonstring-
centeredToggle whether to center modalbooleanfalse
closableToggle whether to show close buttonbooleantrue
contentContentReactNode-
confirmLoadingToggle loading state of confirm buttonbooleanfalse
footerFooterReactNode-
headerHeaderReactNode-
heightHeightnumber-
iconCustomized iconReactNode-
maskToggle whether to show maskbooleantrue
maskClosableToggle whether to allow closing when clicking maskbooleantrue
maskStyleMask styleCSSProperties-
okButtonPropsProperties for confirm buttonButtonProps-
okTextText for confirm buttonstring-
okTypeType for confirm buttonstringprimary
sizeSize of modal, one of small(448px), medium(684px), large(920px), full-width(100vw - 64px)
v >= 0.33.0
string'small'
styleInline styleCSSProperties-
titleTitleReactNode-
widthWidthnumber520
zIndexZ-index value for masknumber1000
onCancelCallback function when clicking cancel button(e: any) => void | Promise<any>-
onOkCallback 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 use Modal.useModal to create a contextHolder and insert to corresponding DOM tree. Modal created by hooks will be able to access the context where contextHolder 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 and Shift + 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 ticketEdit
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
EditEdit 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 use Modal.useModal to create a contextHolder 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 use okText and cancelText 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.

© 2021 - 2022 Semi Design. All rights reserved.

京ICP备19058139号-13浙公网安备 33011002016131号

Designed & Developed with love by Douyin FE & MED