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.
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
| Prop | Type | Description | Default |
|---|---|---|---|
title | string | The title text displayed in the modal header. Used for aria-labelledby. Required. | — |
description | string | A description displayed below the title. Used for aria-describedby. Required. | — |
width | number | string | The width of the modal container. A number is interpreted as pixels. | 452 |
ref | Ref<ModalRef> | A ref exposing imperative open() and close() methods. | — |
closeOnClickOutside | boolean | When true, clicking the backdrop closes the modal. | false |
dismissible | boolean | When 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 |
children | ReactNode | The 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:
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:
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:
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:
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:
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:
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>
);
}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:
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>
</>
);
}