Modal

Demos

How to import


import { Modal } from '@douyinfe/semi-ui';

Basic Usage

Bottom Button Fill up

Set footerFill to true to make the bottom buttons of the Modal footer fill up the arrangement.

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.

By using header, footer, etc, you could create any modal to your needs.

import React from 'react'; import { Modal, Button, List } from '@douyinfe/semi-ui'; import { IconVigoLogo, IconSemiLogo } from '@douyinfe/semi-icons'; class modalDemo extends React.Component { constructor() { super(); this.state = { visible: false }; this.showDialog = this.showDialog.bind(this); this.handleOk = this.handleOk.bind(this); this.handleCancel = this.handleCancel.bind(this); } showDialog() { this.setState({ visible: true }); } handleOk(e) { this.setState({ visible: false }); } handleCancel(e) { this.setState({ visible: false }); } render() { const data = [ { icon: <IconSemiLogo style={{ fontSize: 48 }} />, title: 'Boost new feature adoption with Integration', content: 'Sample data is prepared for you to demostrate how Integration may be useful for your team' }, { icon: <IconVigoLogo style={{ fontSize: 48 }} />, title: 'Introducing Dark Mode', content: 'Sample data is prepared for you to demostrate how Integration may be useful for your team' }, { icon: <IconSemiLogo style={{ fontSize: 48 }} />, title: 'New List Component', content: 'Sample data is prepared for you to demostrate how Integration may be useful for your team' }, ]; const btnStyle = { width: 240, margin: '4px 50px', }; const footer = ( <div style={{ textAlign: 'center' }}> <Button type="primary" theme="solid" onClick={this.handleOk} style={btnStyle}> Continue </Button> <Button type="primary" theme="borderless" onClick={this.handleCancel} style={btnStyle}> Learn more features </Button> </div> ); return ( <> <Button onClick={this.showDialog}>Customized Modal</Button> <Modal header={null} visible={this.state.visible} onOk={this.handleOk} onCancel={this.handleCancel} footer={footer} > <h3 style={{ textAlign: 'center', fontSize: 24, margin: 40 }}>Semi Design New Features</h3> <List dataSource={data} split={false} renderItem={item => ( <List.Item header={item.icon} main={ <div> <h6 style={{ margin: 0, fontSize: 16 }}>{item.title}</h6> <p style={{ marginTop: 4, color: 'var(--semi-color-text-1)' }}>{item.content}</p> </div> } />) } /> </Modal> </> ); } }

set fullScreen={true} can use full screen 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.

The modal content is rendered customly through modalRender, and the draggable Modal is implemented through the DragMove component.

API Reference

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	-
footerFill	Is the bottom button full (>= 2.xx.0 )	boolean	false
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	-
modalContentClass	The class name that can be used to set the style of the dialog content	string	-
modalRender	Custom rendering Modal	(modal: ReactNode) => ReactNode	-
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	-
modalContentClass	The class name that can be used to set the style of the dialog content	string	-
modalRender	Custom rendering Modal	(modal: ReactNode) => ReactNode	-
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.|


const modal = Modal.info();

modal.update({
  title: 'Updated Title',
  content: 'Updated Content',
});

modal.destroy();

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

WAI-ARIA: https://www.w3.org/WAI/ARIA/apg/patterns/alertdialog/

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