Skip to main content
Primitives

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} />;

How inline scripts work

API reference

Modal.Root

PropType
open

Whether the dialog is open, to control it once hydrated: the buttons and Escape then call onOpenChange, and the dialog changes only when open does. Without it, the buttons alone open and close it, which is best unless you need to open or close it yourself.

boolean
onOpenChange

Called when the dialog opens or closes.

(open: boolean, details: ChangeDetails) => void
dialogId

The dialog's id, which the buttons' commandfor names. Defaults to a generated one.

string

Modal.Close

A button that closes the dialog.

PropType
asChild

Render the only child instead, with this part's props merged onto it.

boolean
dialogId

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

PropType
asChild

Render the only child instead, with this part's props merged onto it.

boolean

Modal.Title

The dialog's heading, which names it.

PropType
asChild

Render the only child instead, with this part's props merged onto it.

boolean

Modal.Trigger

A button that opens the dialog as a modal.

PropType
asChild

Render the only child instead, with this part's props merged onto it.

boolean
dialogId

The dialog's id. Set by Root.

string