Skip to content
Browse documentation
whisk/ui

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

tsx
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.

Invite a member

They will receive an email invitation.

Choose a role before sending the invitation.

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.

tsx
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.

tsx
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.

Project settings

Changes apply to every member of this project.

Use the named parts only when this custom anatomy is necessary.

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

PropTypeDefaultDescription
openbooleannoneRequired controlled visibility. An open dialog is shown with the native modal API after hydration; it is closed in server HTML.
onOpenChange(open: boolean) => voidnoneRequired. Update the application-owned open state for close buttons, Escape, backdrop dismissal, and direct native close requests.
titlestringnoneProvide the required visible and accessible dialog name.
description | headingLevel | rolestring | 2–6 | dialog | alertdialognone | 2 | dialogDescribe context when needed, choose the heading level, and use alertdialog only for an urgent confirmation that interrupts the current task.
size | placement | scrollBehaviorsm | md | lg | center | top | inside | outsidemd | center | insideChoose the surface size and placement. inside keeps the header and footer outside the scrolling body; outside scrolls the complete dialog surface.
closeOnEscape | closeOnInteractOutside | showCloseButton | closeLabelboolean | boolean | boolean | stringtrue | true | true | Close modalControl standard dismissal and the accessible label of the built-in close button. Keep a clear cancellation path whenever dismissal is disabled.
initialFocusRef | finalFocusRef{ current: HTMLElement | null }noneOptionally focus an element inside the dialog when it opens or a connected element outside it when it closes.
footer | childrenReactNodenone | nonePlace application-owned actions in footer and the task content in children. Modal does not submit, persist, or close an operation automatically.
className | style | native dialog attributesnative dialog attributesnoneTarget the native dialog. Modal owns its open state, role, accessible name, and modal semantics.
ModalRoot and named partscompound APInoneUse ModalRoot, ModalTrigger, ModalContent, and the named header, body, footer, title, description, close, and action parts only for custom dialog anatomy or an uncontrolled trigger.

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.