---
name: Modal
package: '@wordpress/components'
category: '@wordpress-components'
status: stable
canonical: 'https://system.automattic.design/components/modal/'
storybook: 'https://wordpress.github.io/gutenberg/?path=/docs/components-modal--docs'
github: 'https://github.com/WordPress/gutenberg/tree/trunk/packages/components/src/modal'
figma: 'https://www.figma.com/design/jMgzw8IhsMC4gpMbMko4lv/WPDS--Gutenberg-22.3-?node-id=2036-43132'
---

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

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

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `aria` | `{ describedby?: string \| undefined; labelledby?: string \| undefined; }` | `{ 			labelledby: undefined, 			describedby: undefined, 		}` |  |
| `bodyOpenClassName` | `string` | `'modal-open'` | 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` | `string` | `\`__( 'Close' )\`` | Label on the close button. |
| `contentLabel` | `string` | — | If this property is added, it will be added to the modal content `div` as `aria-label`.<br>Titles are required for accessibility reasons, see `aria.labelledby` and `title` for other ways to provide a title. |
| `focusOnMount` | `Mode \| "firstContentElement" \| undefined` | `true` | Determines focus behavior when the modal opens.<br>- `"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_. |
| `headerActions` | `ReactNode` | `null` | 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. |
| `isDismissible` | `boolean` | `true` | If this property is set to false, the modal will not display a close icon and cannot be dismissed. |
| `isFullScreen` | `boolean` | `false` | 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`.<br>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?: SyntheticEvent<Element, Event> \| KeyboardEvent<HTMLDivElement> \| 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` | `AriaRole \| undefined` | `'dialog'` | If this property is added, it will override the default role of the modal. |
| `shouldCloseOnClickOutside` | `boolean` | `true` | If this property is added, it will determine whether the modal requests to close when a mouse click occurs outside of the modal content. |
| `shouldCloseOnEsc` | `boolean` | `true` | 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`. |
| `title` | `string` | `null` | This property is used as the modal header's title.<br>Titles are required for accessibility reasons, see `aria.labelledby` and `contentLabel` for other ways to provide a title. |
| `__experimentalHideHeader` | `boolean` | `false` | When set to `true`, the Modal's header (including the icon, title and close button) will not be rendered.<br>_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` | — |  |


## Examples

### Default

```tsx
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: small

```tsx
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 Actions

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

```tsx
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>
			) }
		</>
	);
};
```