Skip to main content
Components

Modal

A modal dialog: the page behind is inert until it closes, focus moves into it, and Escape closes it. Where the browser supports invoker commands, it works without JavaScript. Only use a modal when the user must respond before they carry on.

Import

import * as Modal from 'govuk-react/modal';

Examples

Default

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>

With parts

Code
<Modal.Root>
  <Modal.Trigger variant="secondary">Show the timeout warning</Modal.Trigger>
  <Modal.Content>
    <Modal.Title>You’re about to be signed out</Modal.Title>
    <p className="govuk-body">For your security, we will sign you out in 2 minutes.</p>
    <div className="govuk-button-group">
      <Modal.Close variant={undefined}>Stay signed in</Modal.Close>
      <a className="govuk-link" href="#sign-out">
        Sign out
      </a>
    </div>
  </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.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"
  open
>
  <p className="govuk-body">You will not be able to undo this.</p>
</Modal.Composite>

With parts open

The timeout warning, open from the start.

Code
<Modal.Root open>
  <Modal.Trigger variant="secondary">Show the timeout warning</Modal.Trigger>
  <Modal.Content>
    <Modal.Title>You’re about to be signed out</Modal.Title>
    <p className="govuk-body">For your security, we will sign you out in 2 minutes.</p>
    <div className="govuk-button-group">
      <Modal.Close variant={undefined}>Stay signed in</Modal.Close>
      <a className="govuk-link" href="#sign-out">
        Sign out
      </a>
    </div>
  </Modal.Content>
</Modal.Root>

Controlled

Code
<ControlledModal />

API reference

Modal.Root

Holds the modal and the buttons that open and close it.

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 modal. A secondary button, unless you pass another variant, or undefined for a primary one.

PropType
classNamestring
variantButtonVariant
preventDoubleClick

Prevent accidental double clicks on submit buttons from submitting forms multiple times. This has no effect if href is set.

boolean
dialogId

The dialog's id. Set by Root.

string

Modal.Composite

A button that opens a modal with a title, content and actions.

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
triggerTextRequired

The text of the button that opens the modal.

ReactNode
titleRequired

The modal's heading.

ReactNode
closeText

The text of the button that closes the modal. Defaults to "Cancel".

ReactNode
actions

Other actions, such as a button that confirms, shown before the close button.

ReactNode

Modal.Content

The modal dialog. Give it a Title.

No props of its own. Other props are passed to the element it renders.

Modal.Title

The modal's heading, which names it.

No props of its own. Other props are passed to the element it renders.

Modal.Trigger

A button that opens the modal.

PropType
classNamestring
variantButtonVariant
preventDoubleClick

Prevent accidental double clicks on submit buttons from submitting forms multiple times. This has no effect if href is set.

boolean
dialogId

The dialog's id. Set by Root.

string