Modal – Automattic Design System

Modals give users information and choices related to a task they’re trying to accomplish. They can contain critical information, require decisions, or involve multiple tasks.

View on Storybook

View source on GitHub

Import

import { Modal } from '@wordpress/components';

Props

Name	Type	Required	Description
`aria`	{ /** * If this property is added, it will be added to the modal content * `div` as `aria-describedby`. / describedby?: string; /* * If this property is added, it will be added to the modal content * `div` as `aria-labelledby`. Use this when you are rendering the title * yourself within the modal's content area instead of using the `title` * prop. This ensures the title is usable by assistive technology. * * Titles are required for accessibility reasons, see `contentLabel` and * `title` for other ways to provide a title. */ labelledby?: string; }
`bodyOpenClassName`	`string`		Class name added to the body element when the modal is open. @default ‘modal-open’
`children`	`React.ReactNode`	Yes	The children elements.
`className`	`string`		If this property is added, it will an additional class name to the modal content `div`.
`closeButtonLabel`	`string`		Label on the close button. @default `__( 'Close' )`
`contentLabel`	`string`		If this property is added, it will be added to the modal content `div` as `aria-label`. Titles are required for accessibility reasons, see `aria.labelledby` and `title` for other ways to provide a title.
`focusOnMount`	`useFocusOnMount.Mode \| 'firstContentElement'`		Determines focus behavior when the modal opens. `"firstElement"` focuses the first tabbable element within. `"firstInputElement"` focuses the first value control within. `"firstContentElement"` focuses the first tabbable element within the modal’s content element. `true` focuses the element itself. `false` does nothing and should not be used unless an accessible substitute behavior is implemented. @default true
`headerActions`	`React.ReactNode`		Elements that are injected into the modal header to the left of the close button (if rendered). Hidden if `__experimentalHideHeader` is `true`. @default null
`icon`	`React.JSX.Element`		If this property is added, an icon will be added before the title.
`isDismissible`	`boolean`		If this property is set to false, the modal will not display a close icon and cannot be dismissed. @default true
`isFullScreen`	`boolean`		This property when set to `true` will render a full screen modal. @default false
`size`	`'small' \| 'medium' \| 'large' \| 'fill'`		If this property is added it will cause the modal to render at a preset width, or expand to fill the screen. This prop will be ignored if `isFullScreen` is set to `true`. Note: `Modal`‘s width can also be controlled by adjusting the width of the modal’s contents, or via CSS using the `style` prop.
`onKeyDown`	`React.KeyboardEventHandler< HTMLDivElement >`		Handle the key down on the modal frame `div`.
`onRequestClose`	`( event?: React.KeyboardEvent< HTMLDivElement > \| React.SyntheticEvent ) => void`	Yes	This function is called to indicate that the modal should be closed.
`overlayClassName`	`string`		If this property is added, it will an additional class name to the modal overlay `div`.
`role`	`React.AriaRole`		If this property is added, it will override the default role of the modal. @default ‘dialog’
`shouldCloseOnClickOutside`	`boolean`		If this property is added, it will determine whether the modal requests to close when a mouse click occurs outside of the modal content. @default true
`shouldCloseOnEsc`	`boolean`		If this property is added, it will determine whether the modal requests to close when the escape key is pressed. @default true
`style`	`React.CSSProperties`		If this property is added, it will be added to the modal frame `div`.
`title`	`string`		This property is used as the modal header’s title. Titles are required for accessibility reasons, see `aria.labelledby` and `contentLabel` for other ways to provide a title.
`__experimentalHideHeader`	`boolean`		When set to `true`, the Modal’s header (including the icon, title and close button) will not be rendered. Warning: This property is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes. @default false

Examples

Default

const Default = ( { onRequestClose, ...args } ) => {
	const [ isOpen, setOpen ] = useState( false );
	const openModal = () => setOpen( true );
	const closeModal: ModalProps[ 'onRequestClose' ] = ( event ) => {
		setOpen( false );
		onRequestClose( event );
	};

	return (
		<>
			<Button
				__next40pxDefaultSize
				variant="secondary"
				onClick={ openModal }
			>
				Open Modal
			</Button>
			{ isOpen && (
				<Modal onRequestClose={ closeModal } { ...args }>
					<p>
						Lorem ipsum dolor sit amet, consectetur adipiscing elit,
						sed do eiusmod tempor incididunt ut labore et magna
						aliqua. Ut enim ad minim veniam, quis nostrud
						exercitation ullamco laboris nisi ut aliquip ex ea ea
						commodo consequat. Duis aute irure dolor in
						reprehenderit in voluptate velit esse cillum dolore eu
						fugiat nulla pariatur. Excepteur sint occaecat cupidatat
						non proident, sunt in culpa qui officia deserunt mollit
						anim id est laborum.
					</p>

					<InputControl
						__next40pxDefaultSize
						style={ { marginBottom: '20px' } }
					/>

					<Button
						__next40pxDefaultSize
						variant="secondary"
						onClick={ closeModal }
					>
						Close Modal
					</Button>
				</Modal>
			) }
		</>
	);
};

With size: small

const WithsizeSmall = ( { onRequestClose, ...args } ) => {
	const [ isOpen, setOpen ] = useState( false );
	const openModal = () => setOpen( true );
	const closeModal: ModalProps[ 'onRequestClose' ] = ( event ) => {
		setOpen( false );
		onRequestClose( event );
	};

	return (
		<>
			<Button
				__next40pxDefaultSize
				variant="secondary"
				onClick={ openModal }
			>
				Open Modal
			</Button>
			{ isOpen && (
				<Modal onRequestClose={ closeModal } { ...args }>
					<p>
						Lorem ipsum dolor sit amet, consectetur adipiscing elit,
						sed do eiusmod tempor incididunt ut labore et magna
						aliqua. Ut enim ad minim veniam, quis nostrud
						exercitation ullamco laboris nisi ut aliquip ex ea ea
						commodo consequat. Duis aute irure dolor in
						reprehenderit in voluptate velit esse cillum dolore eu
						fugiat nulla pariatur. Excepteur sint occaecat cupidatat
						non proident, sunt in culpa qui officia deserunt mollit
						anim id est laborum.
					</p>

					<InputControl
						__next40pxDefaultSize
						style={ { marginBottom: '20px' } }
					/>

					<Button
						__next40pxDefaultSize
						variant="secondary"
						onClick={ closeModal }
					>
						Close Modal
					</Button>
				</Modal>
			) }
		</>
	);
};

With Header Actions

The headerActions prop can be used to add auxiliary actions to the header, for example a fullscreen mode toggle.

const WithHeaderActions = ( { onRequestClose, ...args } ) => {
	const [ isOpen, setOpen ] = useState( false );
	const openModal = () => setOpen( true );
	const closeModal: ModalProps[ 'onRequestClose' ] = ( event ) => {
		setOpen( false );
		onRequestClose( event );
	};

	return (
		<>
			<Button
				__next40pxDefaultSize
				variant="secondary"
				onClick={ openModal }
			>
				Open Modal
			</Button>
			{ isOpen && (
				<Modal onRequestClose={ closeModal } { ...args }>
					<p>
						Lorem ipsum dolor sit amet, consectetur adipiscing elit,
						sed do eiusmod tempor incididunt ut labore et magna
						aliqua. Ut enim ad minim veniam, quis nostrud
						exercitation ullamco laboris nisi ut aliquip ex ea ea
						commodo consequat. Duis aute irure dolor in
						reprehenderit in voluptate velit esse cillum dolore eu
						fugiat nulla pariatur. Excepteur sint occaecat cupidatat
						non proident, sunt in culpa qui officia deserunt mollit
						anim id est laborum.
					</p>

					<InputControl
						__next40pxDefaultSize
						style={ { marginBottom: '20px' } }
					/>

					<Button
						__next40pxDefaultSize
						variant="secondary"
						onClick={ closeModal }
					>
						Close Modal
					</Button>
				</Modal>
			) }
		</>
	);
};