Modal

A dialog overlay component for displaying focused content that requires user attention or interaction. Renders a title and description in its header, and any children you pass (including action buttons and forms) in its body. Controlled via an imperative ref with open() and close() methods.

Confirm action

Are you sure you want to proceed?

Additional content can be placed here.
import { Button } from "@tenstorrent/vesper/button";
import { Modal, useModal } from "@tenstorrent/vesper/modal";

export default function ModalDemo() {
  const modal = useModal();

  return (
    <>
      <Button onClick={modal.open}>Open modal</Button>
      <Modal
        ref={modal.ref}
        title="Confirm action"
        description="Are you sure you want to proceed?"
      >
        <div
          style={{
            display: "flex",
            flexDirection: "column",
            gap: "var(--vesper-spacing-6)",
          }}
        >
          Additional content can be placed here.
          <div
            style={{
              display: "flex",
              justifyContent: "flex-end",
              gap: "var(--vesper-spacing-4)",
            }}
          >
            <Button variant="tertiary" onClick={modal.close}>
              Cancel
            </Button>
            <Button onClick={modal.close}>Confirm</Button>
          </div>
        </div>
      </Modal>
    </>
  );
}

Options

PropTypeDescriptionDefault
titlestringThe title text displayed in the modal header. Used for aria-labelledby. Required.—
descriptionstringA description displayed below the title. Used for aria-describedby. Required.—
widthnumber | stringThe width of the modal container. A number is interpreted as pixels.452
refRef<ModalRef>A ref exposing imperative open() and close() methods.—
closeOnClickOutsidebooleanWhen true, clicking the backdrop closes the modal.false
dismissiblebooleanWhen false, the user can't dismiss the modal: Escape and backdrop clicks are ignored, and the header close button is disabled. close() still works.true
childrenReactNodeThe content displayed inside the modal body, such as text, action buttons, or a form.—

All other props are forwarded to the underlying <dialog> element.

A Modal always blocks interaction with the rest of the page while it is open. When the user should be able to keep working with the content behind the panel, reach for the Sheet component in popover mode instead.

Examples

Opening and closing a modal

A Modal renders closed, and is opened imperatively. The useModal hook returns everything needed for this: a ref to pass to the modal, plus open() and close() functions:

Welcome

Thanks for signing up.

You can start exploring features right away.
import { Button } from "@tenstorrent/vesper/button";
import { Modal, useModal } from "@tenstorrent/vesper/modal";

export default function BasicModal() {
  const modal = useModal();

  return (
    <>
      <Button onClick={modal.open}>Open modal</Button>
      <Modal
        ref={modal.ref}
        title="Welcome"
        description="Thanks for signing up."
      >
        You can start exploring features right away.
      </Modal>
    </>
  );
}

Modal renders a native <dialog>, so an open modal traps focus, blocks interaction with the rest of the page, and closes when the user presses Escape. The close button in the header closes it too.

To stop users from being able to close a modal, (for example, if you're rendering a form inside a modal), see Preventing dismissal.

Action buttons

To add action buttons to a modal, render them as children, alongside the rest of the modal's content. Call close() from a button's onClick handler to close the modal:

Delete item

This action cannot be undone.

import { Button } from "@tenstorrent/vesper/button";
import { Modal, useModal } from "@tenstorrent/vesper/modal";

export default function ModalWithButtons() {
  const modal = useModal();

  return (
    <>
      <Button variant="danger" onClick={modal.open}>
        Delete item
      </Button>
      <Modal
        ref={modal.ref}
        title="Delete item"
        description="This action cannot be undone."
      >
        <div
          style={{
            display: "flex",
            justifyContent: "flex-end",
            gap: "var(--vesper-spacing-4)",
          }}
        >
          <Button variant="tertiary" onClick={modal.close}>
            Cancel
          </Button>
          <Button variant="danger" onClick={modal.close}>
            Delete
          </Button>
        </div>
      </Modal>
    </>
  );
}

You control how the buttons are laid out. To have them share the full width of the modal, give each button flex: 1:

Save changes

Your changes have not been saved yet.

import { Button } from "@tenstorrent/vesper/button";
import { Modal, useModal } from "@tenstorrent/vesper/modal";

export default function ModalButtonsLayout() {
  const modal = useModal();

  return (
    <>
      <Button onClick={modal.open}>Open modal</Button>
      <Modal
        ref={modal.ref}
        title="Save changes"
        description="Your changes have not been saved yet."
      >
        <div style={{ display: "flex", gap: "var(--vesper-spacing-4)" }}>
          <Button variant="tertiary" style={{ flex: 1 }} onClick={modal.close}>
            Discard
          </Button>
          <Button style={{ flex: 1 }} onClick={modal.close}>
            Save
          </Button>
        </div>
      </Modal>
    </>
  );
}

Sizing

A modal is 452px wide by default. Pass width to change that, either as a number (interpreted as pixels) or as any CSS length string.

The modal grows to fit its content. To keep long content from making it too tall, wrap that content in a scrollable element with a maxHeight:

Release notes

Everything that changed in this release.

Added a dark theme, which follows your system preference by default.

Added keyboard shortcuts for the most common actions.

Improved search performance across large projects.

Improved the layout of settings pages on small screens.

Fixed an issue where notifications were sometimes shown twice.

Fixed an issue where exported files used the wrong time zone.

import { Button } from "@tenstorrent/vesper/button";
import { Modal, useModal } from "@tenstorrent/vesper/modal";
import { Typography } from "@tenstorrent/vesper/typography";

const RELEASE_NOTES = [
  "Added a dark theme, which follows your system preference by default.",
  "Added keyboard shortcuts for the most common actions.",
  "Improved search performance across large projects.",
  "Improved the layout of settings pages on small screens.",
  "Fixed an issue where notifications were sometimes shown twice.",
  "Fixed an issue where exported files used the wrong time zone.",
];

export default function WideModal() {
  const modal = useModal();

  return (
    <>
      <Button onClick={modal.open}>Open wide modal</Button>
      <Modal
        ref={modal.ref}
        width={640}
        title="Release notes"
        description="Everything that changed in this release."
      >
        <div
          style={{
            display: "flex",
            flexDirection: "column",
            gap: "var(--vesper-spacing-6)",
          }}
        >
          <div
            role="region"
            aria-label="Release notes"
            tabIndex={0}
            style={{
              display: "flex",
              flexDirection: "column",
              gap: "var(--vesper-spacing-4)",
              maxHeight: "8rem",
              overflowY: "auto",
            }}
          >
            {RELEASE_NOTES.map((note) => (
              <Typography key={note}>{note}</Typography>
            ))}
          </div>
          <div style={{ display: "flex", justifyContent: "flex-end" }}>
            <Button onClick={modal.close}>Close</Button>
          </div>
        </div>
      </Modal>
    </>
  );
}

Closing on click outside

Clicking the backdrop does nothing by default, which keeps users from dismissing a modal by accident. Pass closeOnClickOutside to allow users to dismiss a modal by clicking the backdrop:

Keyboard shortcuts

Press Escape or click outside to dismiss.

This modal can be dismissed by clicking the backdrop behind it.
import { Button } from "@tenstorrent/vesper/button";
import { Modal, useModal } from "@tenstorrent/vesper/modal";

export default function DismissibleModal() {
  const modal = useModal();

  return (
    <>
      <Button onClick={modal.open}>Open modal</Button>
      <Modal
        ref={modal.ref}
        closeOnClickOutside
        title="Keyboard shortcuts"
        description="Press Escape or click outside to dismiss."
      >
        This modal can be dismissed by clicking the backdrop behind it.
      </Modal>
    </>
  );
}

Usage in forms

To use a modal as a form, render a <form> element as its children, with the form's fields and action buttons inside it. A button with type="submit" then submits the form natively, and native validation runs before the submit handler fires:

Create project

Enter the details for your new project.

import { useState } from "react";

import { Button } from "@tenstorrent/vesper/button";
import { Modal, useModal } from "@tenstorrent/vesper/modal";
import { TextInput } from "@tenstorrent/vesper/text-input";
import { Typography } from "@tenstorrent/vesper/typography";

export default function FormModal() {
  const modal = useModal();
  const [submitted, setSubmitted] = useState<string | null>(null);

  return (
    <div
      style={{
        display: "flex",
        flexDirection: "column",
        gap: "var(--vesper-spacing-4)",
        alignItems: "flex-start",
      }}
    >
      <Button onClick={modal.open}>Create project</Button>
      {submitted && (
        <Typography variant="copy-sm">Created project: {submitted}</Typography>
      )}
      <Modal
        ref={modal.ref}
        title="Create project"
        description="Enter the details for your new project."
      >
        <form
          style={{
            display: "flex",
            flexDirection: "column",
            gap: "var(--vesper-spacing-6)",
          }}
          onSubmit={(event) => {
            event.preventDefault();
            const data = new FormData(event.currentTarget);
            setSubmitted(String(data.get("name") ?? ""));
            modal.close();
          }}
        >
          <TextInput
            required
            aria-label="Project name"
            placeholder="Project name"
            name="name"
          />
          <div
            style={{
              display: "flex",
              justifyContent: "flex-end",
              gap: "var(--vesper-spacing-4)",
            }}
          >
            <Button variant="tertiary" type="button" onClick={modal.close}>
              Cancel
            </Button>
            <Button type="submit">Create</Button>
          </div>
        </form>
      </Modal>
    </div>
  );
}
Buttons rendered inside a form default to type="submit", so give any button that should not submit an explicit type="button", as the cancel button above does.

Preventing dismissal

Some flows shouldn't be interrupted, such as while a form is submitting a request. Set dismissible to false to stop users from closing the modal: pressing Escape and clicking the backdrop do nothing, and the close button in the header is disabled. Calling close() still closes the modal, so you can close it yourself once the flow completes.

Tie dismissible to your own state so it only blocks dismissal while it matters. Disable your own cancel button for the same period:

Invite teammate

Send an email invitation to join your workspace.

import { useState } from "react";

import { Button } from "@tenstorrent/vesper/button";
import { Modal, useModal } from "@tenstorrent/vesper/modal";
import { TextInput } from "@tenstorrent/vesper/text-input";

export default function NonDismissibleModal() {
  const modal = useModal();
  const [isSubmitting, setIsSubmitting] = useState(false);

  return (
    <>
      <Button onClick={modal.open}>Invite teammate</Button>
      <Modal
        ref={modal.ref}
        title="Invite teammate"
        description="Send an email invitation to join your workspace."
        dismissible={!isSubmitting}
      >
        <form
          style={{
            display: "flex",
            flexDirection: "column",
            gap: "var(--vesper-spacing-6)",
          }}
          onSubmit={async (event) => {
            event.preventDefault();
            setIsSubmitting(true);
            // simulate a slow network request
            await new Promise((resolve) => setTimeout(resolve, 3000));
            setIsSubmitting(false);
            modal.close();
          }}
        >
          <TextInput
            required
            type="email"
            aria-label="Email address"
            placeholder="Email address"
            name="email"
          />
          <div
            style={{
              display: "flex",
              justifyContent: "flex-end",
              gap: "var(--vesper-spacing-4)",
            }}
          >
            <Button
              variant="tertiary"
              type="button"
              onClick={modal.close}
              disabled={isSubmitting}
            >
              Cancel
            </Button>
            <Button type="submit" disabled={isSubmitting}>
              {isSubmitting ? "Sending…" : "Send invite"}
            </Button>
          </div>
        </form>
      </Modal>
    </>
  );
}