Documentation index for AI agents (llms.txt). Markdown versions of every page are available by appending .md to the page URL. The full corpus is at /llms-full.txt.

Modal

The Modal component renders an animated dialog on top of the page. It portals into document.body so the overlay always sits above transformed or clipped ancestors, and it closes on Escape, on a click outside, or with the built-in close button.

The Modal is a controlled component: the parent owns the open state. The dialog surface carries role="dialog" and aria-modal="true", and takes its accessible name from $title.

For design guidelines and all interactive states, see the Overlays design page.

"use client";
import React, { useState } from "react";
import { Button, Modal } from "cherry-styled-components";

export default function Page() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <>
      <Button onClick={() => setIsOpen(true)}>Open Modal</Button>
      <Modal
        $isOpen={isOpen}
        $onClose={() => setIsOpen(false)}
        $title="Modal Title"
      >
        Modal content goes here.
      </Modal>
    </>
  );
}

With a custom width for larger content:

<Modal $isOpen={isOpen} $onClose={close} $width={800}>
  Content
</Modal>

Stacking

Modals stack. When a modal opens over one that is already open (a "confirm with a code" step over a form, say), only one card shows at a time: the open modal's card sinks out first, then the new card rises in over the same backdrop. Closing the top modal plays it backwards, and the one underneath comes back.

The modal underneath stays mounted while it is covered, so whatever was typed in it is still there when it returns. It also ignores Escape and clicks outside while covered: those belong to the modal on top.

<Modal $isOpen={isFormOpen} $onClose={closeForm} $title="Invite a teammate">
  <Button onClick={() => setIsCodeOpen(true)}>Send invite</Button>
</Modal>
<Modal $isOpen={isCodeOpen} $onClose={closeCode} $title="Enter your code">
  Content
</Modal>

To keep the previous behaviour for one modal, where it and the ones opened over it show at the same time, pass $stack={false}.

Full-page layers

A full-page layer that is not a Modal (an outage screen, a sign-in wall) can join the same stack with useModalLayer. While open is true, any open modal fades away under it, and it comes back once the layer is gone. It returns whether another layer covers this one.

"use client";
import { useModalLayer } from "cherry-styled-components";

function OutageScreen({ open }) {
  useModalLayer(open);
  return open ? <FullPageCover /> : null;
}

Restyling

To restyle the modal from your app, pass a className (or style). Both are applied to the overlay root, and the inner parts expose stable class hooks: .modal-inner, .modal-close, .modal-title, and .modal-content.

<Modal $isOpen={isOpen} $onClose={close} className="checkout-modal">
  Content
</Modal>
.checkout-modal .modal-inner {
  border-radius: 24px;
}

Wrapping with styled(Modal) does not work: styled-components strips transient $-props before they reach the wrapped component, so the modal never receives $isOpen or $onClose. Target a passed class instead.

Properties

childrenReact.ReactNode

The modal content. It scrolls internally when taller than the viewport.

$isOpenbooleanrequired

Whether the modal is visible. The modal animates in and out on change.

$onClose() => voidrequired

Called when the user dismisses the modal (Escape, outside click, or the close button).

$titlestring

Optional title rendered with a divider below it. Also used as the dialog's aria-label.

$widthnumber

Maximum width in pixels on large screens. Falls back to 500px when unset.

$hideCloseButtonboolean

Omits the built-in close button in the top-right corner. Escape and outside click still dismiss the modal.

$stackboolean

Whether the modal joins the modal stack. Defaults to true: a modal opened over this one hides it until it closes. Pass false to let this modal and the ones opened over it show at the same time.

classNamestring

Applied to the overlay root, for app-level restyling. See the Restyling section above.

styleReact.CSSProperties

Inline styles applied to the overlay root.

The Modal is SSR-safe: it renders nothing on the server and during the first client render, then portals once hydration has completed.

The modal unmounts its children once the exit animation finishes, so state inside the modal (such as form inputs) resets between openings. To keep state across openings, lift it into the parent.