Modal

Our Modal component has some important features you won't find in a standard component library.

• It uses the native <dialog> element.
• By default, it is always mounted into the DOM - even when the modal is closed. This means the dialog content won't be hidden from Google and will contribute towards SEO.

<ModalRoot>
  <ModalTrigger asChild>
    <Button>Open Modal</Button>
  </ModalTrigger>
  <Modal>
    <ModalBackdrop />
    <ModalContent>
      <ModalCloseButton />
      <ModalIcon className="mb-6">
        <RiShapesLine />
      </ModalIcon>
      <ModalTitle>This is a modal title</ModalTitle>
      <ModalText>
        It should probably say something useful here... but this is just an
        example. You can close this modal by hitting the escape key, or by
        clicking the close button in the top right corner.
      </ModalText>
      <ModalFooter>
        <ModalAction>
          <Button variant="secondary">Cancel</Button>
        </ModalAction>
        <ModalAction>
          <Button>Confirm</Button>
        </ModalAction>
      </ModalFooter>
    </ModalContent>
  </Modal>
</ModalRoot>

Modal icons

The <ModalIcon> has a few different variants. Each variant comes with a default icon, but you can render any icon as a child to override the default.

Default icons

<ModalIcon variant="success" />

Custom icons

<ModalIcon variant="success">
  <RiShapesLine />
</ModalIcon>

Controlled

To use as a controlled modal you need to:

1. Pass a boolean isOpen prop to the <ModalRoot>.
2. Pass an onClose handler to the <ModalRoot>. This is called when something inside the modal calls a close event (e.g. hitting escape).
3. Open the modal via an onClick on the <ModalTrigger>, or via some other event.

export const ControlledModal = () => {
  const [isOpen, setIsOpen] = useState(false);
 
  return (
    <ModalRoot isOpen={isOpen} onClose={() => setIsOpen(false)}>
      <ModalTrigger asChild>
        <Button onClick={() => setIsOpen(true)}>Open Modal</Button>
      </ModalTrigger>
      <Modal>
        <ModalBackdrop />
        <ModalContent>
          <ModalCloseButton />
          <ModalIcon className="mb-6">
            <RiShapesLine />
          </ModalIcon>
          <ModalTitle>This is controlled a modal</ModalTitle>
          <ModalText>
            This modal is controlled by a boolean prop on the ModalRoot
            component.
          </ModalText>
          <ModalFooter>
            <ModalAction>
              <Button variant="secondary">Cancel</Button>
            </ModalAction>
            <ModalAction>
              <Button>Save</Button>
            </ModalAction>
          </ModalFooter>
        </ModalContent>
      </Modal>
    </ModalRoot>
  );
};

Async Actions

Modal Action buttons can take async functions as their onClick prop. While pending the action child receives an isLoading prop, and when the callback resolves the modal closes.

<ModalAction
  onClick={async () => {
    await login();
  }}
>
  <Button>Login</Button>
</ModalAction>

To prevent the modal from closing you can call event.preventDefault() in the onClick callback. You might want to do this in the case that the callback fails, for example, when making an API call.

<ModalAction
  onClick={async (event) => {
    try {
      await login();
    } catch (error) {
      event.preventDefault(); // Prevent the modal from closing
      setError(error.message); // Handle the error
    }
  }}
>
  <Button>Login</Button>
</ModalAction>

Dismiss on backdrop click

If you want you can make the modal dismissable by clicking the backdrop you can pass the dismissOnClick prop to the <ModalBackdrop>.

<Modal>
  <ModalBackdrop dismissOnClick />
  <ModalContent>...</ModalContent>
</Modal>

Portals

You can also pass a container prop to the Modal component to render the modal in a different container. This might be helpful if you want to open a modal from inside a container that has overflow: hidden;.

<Modal container={container}>
  <ModalBackdrop />
  <ModalContent>...</ModalContent>
</Modal>

Unmount when closed

You can choose to unmount the modal when it is closed by passing the dangerouslyUnmountWhenClosed prop to the Modal Root component.

<ModalRoot dangerouslyUnmountWhenClosed>
  <ModalTrigger asChild>
    <Button>Open Modal</Button>
  </ModalTrigger>
  <Modal>
    <ModalBackdrop />
    <ModalContent>
      <ModalCloseButton />
      <ModalTitle>This is a modal</ModalTitle>
    </ModalContent>
  </Modal>
</ModalRoot>

Requirements

The following libraries need to be installed:

The following files and folders need to be copied to your project:

Components

<ModalRoot />

Required at the top level. Provides context and manages open/close state for all descendant Modal components.

Can be used uncontrolled (open state managed internally via <ModalTrigger />) or controlled by passing isOpen and onClose.

Props

<ModalTrigger />

A button that opens the modal when clicked. Use asChild to render as a custom element such as <Button>.

Props

Data attributes

<Modal />

The native <dialog> element. Must be placed inside <ModalRoot />.

Props

Data attributes

<ModalBackdrop />

A full-screen overlay rendered behind the modal content. Applies a semi-transparent blurred backdrop.

Props

Data attributes

<ModalContent />

A container for the modal body. Handles entry and exit animations.

Props

Data attributes

<ModalCloseButton />

A pre-styled close button positioned in the top-right corner of the modal. Receives focus automatically when the modal opens.

Props

Data attributes

<ModalAction />

Wraps an action element (typically a <Button>) that closes the modal when clicked. Supports async onClick handlers — while the handler is pending, the child receives a loading prop. When the handler resolves the modal closes. Call event.preventDefault() to prevent the modal from closing (e.g. after a failed API call).

Props

Data attributes

<ModalTitle />

The modal title rendered as an <h2>. When present, automatically links to the dialog via aria-labelledby.

Props

<ModalText />

A simple presentation container for text content.

Props

<ModalIcon />

Display a pretty icon at the top of the modal.

Props

<ModalFooter />

A flex row container for action buttons, aligned to the right.

Props

Hooks

useDialogContext()

Call from inside <ModalRoot /> to access and control the modal state. Useful for building custom controls that need to open or close the modal programmatically.

Returns