Modal
Focus attention on a task or decision.
Overview
Modal is a controlled native modal dialog for a focused, blocking task. The browser owns its top layer, background inertness, and focus containment; your application owns whether it is open and what its actions do.
Use when
A focused task or decision must temporarily block interaction with the page behind it.
Use instead
Use Flyout or DropdownMenu for short contextual choices, a form in the page for non-blocking work, and Toast for non-blocking result feedback.
Usage
import { useState } from "react";
import { Button, Modal, StackRow, Text } from "@smoothie-framework/whisk-react";
export function DeleteProjectDialog() {
const [open, setOpen] = useState(false);
return <>
<Button variant="destructive" onClick={() => setOpen(true)}>Delete project</Button>
<Modal
open={open}
onOpenChange={setOpen}
title="Delete project?"
description="This cannot be undone."
footer={<StackRow justify="end" gap={3}>
<Button variant="secondary" onClick={() => setOpen(false)}>Cancel</Button>
<Button variant="destructive" onClick={() => { /* Delete, then close. */ setOpen(false); }}>
Delete project
</Button>
</StackRow>}
>
<Text>The project and its members will be removed.</Text>
</Modal>
</>;
}Examples
Control the dialog state
Modal is controlled: the trigger, close button, Escape, and backdrop all call onOpenChange. Update the same application-owned state from every route that should close the dialog.
import { useState } from "react";
import { Button, Modal, StackRow, Text } from "@smoothie-framework/whisk-react";
export function InviteMemberDialog() {
const [open, setOpen] = useState(false);
return <>
<Button onClick={() => setOpen(true)}>Invite member</Button>
<Modal
open={open}
onOpenChange={setOpen}
title="Invite a member"
description="They will receive an email invitation."
footer={<StackRow justify="end" gap={3}>
<Button variant="secondary" onClick={() => setOpen(false)}>Cancel</Button>
<Button onClick={() => setOpen(false)}>Send invitation</Button>
</StackRow>}
>
<Text>Choose a role before sending the invitation.</Text>
</Modal>
</>;
}Use alertdialog only for an urgent interruption
A destructive action is not automatically an alert dialog. Use alertdialog when the interruption itself is urgent, and direct focus to the safe choice when the dialog opens.
import { useRef, useState } from "react";
import { Button, Modal, StackRow, Text } from "@smoothie-framework/whisk-react";
export function ExpiringSessionDialog() {
const [open, setOpen] = useState(false);
const staySignedInRef = useRef<HTMLButtonElement | null>(null);
return <>
<Button onClick={() => setOpen(true)}>Preview session warning</Button>
<Modal
open={open}
onOpenChange={setOpen}
role="alertdialog"
title="Your session is about to expire"
description="You can remain signed in or leave the workspace."
initialFocusRef={staySignedInRef}
footer={<StackRow justify="end" gap={3}>
<Button ref={staySignedInRef} variant="secondary" onClick={() => setOpen(false)}>
Stay signed in
</Button>
<Button variant="destructive" onClick={() => setOpen(false)}>Leave workspace</Button>
</StackRow>}
>
<Text>Unsaved changes may be lost when the session ends.</Text>
</Modal>
</>;
}Choose where long content scrolls
inside keeps the dialog heading and footer available while its body scrolls. outside scrolls the whole surface. Keep the body focused on one task rather than putting a long document into a modal.
import { Modal, Text } from "@smoothie-framework/whisk-react";
<Modal
open={open}
onOpenChange={setOpen}
title="Terms for the private preview"
scrollBehavior="inside"
>
<Text>Long content scrolls inside the dialog body.</Text>
</Modal>
<Modal
open={open}
onOpenChange={setOpen}
title="Terms for the private preview"
scrollBehavior="outside"
>
<Text>The entire dialog surface scrolls.</Text>
</Modal>Use named parts for custom anatomy
The convenience Modal is the default. Use ModalRoot and its parts when an application needs an uncontrolled trigger, custom header or footer placement, or a composed content structure.
import {
Button,
ModalActionTrigger,
ModalBody,
ModalContent,
ModalDescription,
ModalFooter,
ModalHeader,
ModalRoot,
ModalTitle,
ModalTrigger,
Text,
} from "@smoothie-framework/whisk-react";
<ModalRoot>
<ModalTrigger asChild><Button variant="secondary">Open project settings</Button></ModalTrigger>
<ModalContent>
<ModalHeader>
<ModalTitle>Project settings</ModalTitle>
<ModalDescription>Changes apply to every member of this project.</ModalDescription>
</ModalHeader>
<ModalBody><Text>Custom dialog content.</Text></ModalBody>
<ModalFooter><ModalActionTrigger asChild><Button>Done</Button></ModalActionTrigger></ModalFooter>
</ModalContent>
</ModalRoot>Props
Component props
Accessibility
Modal uses the browser's native modal dialog top layer: the page behind is inert and focus is contained while it is open. Its required title labels the dialog; description is attached only when supplied. The default close button has an accessible label, and Escape or a completed backdrop press requests close unless disabled. Use dialog for ordinary blocking tasks and alertdialog only for urgent confirmation. Put focus on a safe, useful control with initialFocusRef when the default is not appropriate, especially for a destructive decision, and provide finalFocusRef when a predictable close target matters. Do not use a modal for passive information, do not remove its cancellation route without a clear reason, and do not assume it provides action submission, a portal API, an overlay stack, or a non-modal mode.
Content guidance
Use a title that states the decision or task. A destructive confirm button should name the consequence, and a dismissal action should say Cancel.