Modal
A native dialog opened and closed by invoker commands, working without JavaScript where the browser supports them.
Used by govuk-react's modal.
Unstyled
The primitive on plain elements, with no GOV.UK markup or styles: what you start from in your own library.
Default
Code
<Modal.Root>
<Modal.Trigger>Delete account</Modal.Trigger>
<Modal.Content>
<Modal.Title>Are you sure you want to delete your account?</Modal.Title>
<p>You cannot undo this.</p>
<Modal.Close>Cancel</Modal.Close>
</Modal.Content>
</Modal.Root>Open
Open from the start, for visual regression. Left out of the docs page, where it would cover everything else.
Code
<Modal.Root open>
<Modal.Trigger>Delete account</Modal.Trigger>
<Modal.Content>
<Modal.Title>Are you sure you want to delete your account?</Modal.Title>
<p>You cannot undo this.</p>
<Modal.Close>Cancel</Modal.Close>
</Modal.Content>
</Modal.Root>In govuk-react
govuk-react's modal, built with this primitive.
Code
<Modal.Composite
triggerText="Delete account"
title="Are you sure you want to delete your account?"
actions={(
<button type="submit" className="govuk-button govuk-button--warning" form="delete-account">
Yes, delete my account
</button>
)}
closeText="Cancel"
>
<p className="govuk-body">You will not be able to undo this.</p>
</Modal.Composite>Usage
import * as Modal from '@govuk-react/primitives/modal';
<Modal.Root>
<Modal.Trigger>Delete account</Modal.Trigger>
<Modal.Content>
<Modal.Title>Are you sure?</Modal.Title>
<Modal.Close>Cancel</Modal.Close>
</Modal.Content>
</Modal.Root>;
Content is a native dialog, and Trigger and Close are buttons with invoker commands (command="show-modal" and command="close", with commandfor naming the dialog). Where the browser supports them (Chrome and Edge 135, Firefox 144, Safari 26.2), the dialog opens as a true modal without JavaScript: the page behind is inert, focus moves into the dialog and Escape closes it. In older browsers, the <govuk-react-modal> element runs the commands once its script loads.
Title names the dialog, so always include one, or pass aria-label to Content. Pass closedby="any" to Content to also close it when the user clicks outside it.
open and onOpenChange control the dialog once hydrated: Trigger, Close and Escape then call onOpenChange, and the dialog changes only when open does. See Controlled state for its limits. In an island without a Root, pass dialogId to Trigger and Close, and id and aria-labelledby to Content.
Inline script
To make the markup interactive before React hydrates, inline @govuk-react/primitives/inline/modal-element.js, or render it from React on the server:
import { InlineScript, modal } from '@govuk-react/primitives/inline-script';
<InlineScript script={modal} nonce={nonce} />;API reference
Modal.Root
| Prop | Type |
|---|---|
openWhether the dialog is open, to control it once hydrated: the buttons and Escape then call
| boolean |
onOpenChangeCalled when the dialog opens or closes. | (open: boolean, details: ChangeDetails) => void |
dialogIdThe dialog's id, which the buttons' | string |
Modal.Close
A button that closes the dialog.
| Prop | Type |
|---|---|
asChildRender the only child instead, with this part's props merged onto it. | boolean |
dialogIdThe dialog's id. Set by Root. | string |
Modal.Content
The dialog. It's named by Title, unless you pass aria-labelledby or aria-label. Pass
closedby="any" to also close it when the user clicks outside it.
| Prop | Type |
|---|---|
asChildRender the only child instead, with this part's props merged onto it. | boolean |
Modal.Title
The dialog's heading, which names it.
| Prop | Type |
|---|---|
asChildRender the only child instead, with this part's props merged onto it. | boolean |
Modal.Trigger
A button that opens the dialog as a modal.
| Prop | Type |
|---|---|
asChildRender the only child instead, with this part's props merged onto it. | boolean |
dialogIdThe dialog's id. Set by Root. | string |