Automattic Design System

Components

Modal

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.

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

View on Storybook

View in Figma

View source on GitHub

PropsPermalink to this section

NameDefaultDescription
aria{ labelledby: undefined, describedby: undefined, }

{ describedby?: string | undefined; labelledby?: string | undefined; }

bodyOpenClassName'modal-open'

string

Class name added to the body element when the modal is open. If you use a custom class name, its styles must set overflow: hidden to preserve the Modal’s scroll lock.

children Required

ReactNode

The children elements.

className

string

If this property is added, it will an additional class name to the modal content div.

closeButtonLabel`__( 'Close' )`

string

Label on the close button.

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.

focusOnMounttrue

Mode | "firstContentElement" | undefined

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

ReactNode

Elements that are injected into the modal header to the left of the close button (if rendered). Hidden if __experimentalHideHeader is true.

icon

Element

If this property is added, an icon will be added before the title.

isDismissibletrue

boolean

If this property is set to false, the modal will not display a close icon and cannot be dismissed.

isFullScreenfalse

boolean

This property when set to true will render a full screen modal.

size

"small" | "fill" | "medium" | "large"

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

KeyboardEventHandler<HTMLDivElement>

Handle the key down on the modal frame div.

onRequestClose Required

(event?: KeyboardEvent<HTMLDivElement> | SyntheticEvent<Element, Event> | undefined) => void

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'dialog'

AriaRole | undefined

If this property is added, it will override the default role of the modal.

shouldCloseOnClickOutsidetrue

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.

shouldCloseOnEsctrue

boolean

If this property is added, it will determine whether the modal requests to close when the escape key is pressed.

style

CSSProperties

If this property is added, it will be added to the modal frame div.

titlenull

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.

__experimentalHideHeaderfalse

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.

ref

LegacyRef<HTMLDivElement> | undefined

Allows getting a ref to the component instance. Once the component unmounts, React will set ref.current to null (or call the ref with null if you passed a callback ref).

key

Key | null | undefined

ExamplesPermalink to this section

DefaultPermalink to this section

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 style={ { marginBottom: '20px' } } />

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

With size: smallPermalink to this section

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 style={ { marginBottom: '20px' } } />

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

With Header ActionsPermalink to this section

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 style={ { marginBottom: '20px' } } />

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