Dialog

A modal that interrupts the user with important content.

Default

A focused task with a title, fields and a footer. DialogClose renders the footer buttons so both actions close the dialog.

import {
  Button,
  Dialog,
  DialogBody,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
  Field,
  FieldLabel,
  Fieldset,
  FieldsetLegend,
  Input,
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue,
} from "@smallest-inc/ui";

const environments = [
  { label: "Production", value: "production" },
  { label: "Staging", value: "staging" },
];

export default function DialogDefault() {
  return (
    <Dialog>
      <DialogTrigger render={<Button variant="secondary" />}>Create view</DialogTrigger>
      <DialogContent>
        <DialogBody className="flex flex-col gap-6">
          <DialogHeader>
            <DialogTitle>Create view</DialogTitle>
            <DialogDescription>Group calls from your agents into a view you can monitor.</DialogDescription>
          </DialogHeader>
          <Fieldset>
            <FieldsetLegend className="sr-only">View details</FieldsetLegend>
            <Field>
              <FieldLabel>View name</FieldLabel>
              <Input placeholder="Escalated support calls" />
            </Field>
            <Field>
              <FieldLabel>
                Description <span className="font-normal text-fg-secondary">Optional</span>
              </FieldLabel>
              <Input placeholder="What this view tracks" />
            </Field>
            <Field>
              <FieldLabel>Environment</FieldLabel>
              <Select items={environments}>
                <SelectTrigger>
                  <SelectValue placeholder="Choose environment" />
                </SelectTrigger>
                <SelectContent>
                  {environments.map((environment) => (
                    <SelectItem key={environment.value} value={environment.value}>
                      {environment.label}
                    </SelectItem>
                  ))}
                </SelectContent>
              </Select>
            </Field>
          </Fieldset>
        </DialogBody>
        <DialogFooter>
          <DialogClose render={<Button variant="transparent" />}>Cancel</DialogClose>
          <DialogClose render={<Button />}>Create view</DialogClose>
        </DialogFooter>
      </DialogContent>
    </Dialog>
  );
}

Close button

Pass showCloseButton for long or scrollable content. The body scrolls under a fixed footer; pad the header so the title clears the button.

import {
  Button,
  Dialog,
  DialogBody,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
  Entity,
  EntityContent,
  EntityMedia,
  Fieldset,
  FieldsetLegend,
  List,
  ListItem,
} from "@smallest-inc/ui";

const tools = [
  "Search contacts",
  "Get contact",
  "Create contact",
  "Get deal",
  "Update deal",
  "Log call",
  "Create task",
];

export default function DialogCloseButton() {
  return (
    <Dialog>
      <DialogTrigger render={<Button variant="secondary" />}>Add tools</DialogTrigger>
      <DialogContent showCloseButton>
        <DialogBody className="flex max-h-88 flex-col gap-6">
          <DialogHeader className="pr-8">
            <DialogTitle>Add HubSpot tools</DialogTitle>
            <DialogDescription>Choose the tools your agent can call during a conversation.</DialogDescription>
          </DialogHeader>
          <Fieldset>
            <FieldsetLegend>Tools</FieldsetLegend>
            <List>
              {tools.map((tool) => (
                <ListItem key={tool} checkbox checkboxLabel={`Add ${tool}`}>
                  <Entity className="gap-2">
                    <EntityMedia />
                    <EntityContent title={tool} />
                  </Entity>
                </ListItem>
              ))}
            </List>
          </Fieldset>
        </DialogBody>
        <DialogFooter>
          <DialogClose render={<Button variant="transparent" />}>Cancel</DialogClose>
          <DialogClose render={<Button />}>Add tools</DialogClose>
        </DialogFooter>
      </DialogContent>
    </Dialog>
  );
}

Destructive

Lead with DialogIcon, name the object in the title and action, and put the consequence in a DialogNotice. Keep the action disabled until the name is typed.

import { useState } from "react";
import {
  Button,
  Dialog,
  DialogBody,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogIcon,
  DialogNotice,
  DialogTitle,
  DialogTrigger,
  Field,
  FieldLabel,
  Input,
  TriangleAlertIcon,
} from "@smallest-inc/ui";

const agentName = "Support agent";

export default function DialogDestructive() {
  const [confirmation, setConfirmation] = useState("");

  return (
    <Dialog onOpenChange={(open) => open && setConfirmation("")}>
      <DialogTrigger render={<Button variant="danger" />}>Delete agent</DialogTrigger>
      <DialogContent>
        <DialogBody className="flex flex-col gap-6">
          <DialogIcon>
            <TriangleAlertIcon radius="2" />
          </DialogIcon>
          <DialogHeader>
            <DialogTitle>Delete agent</DialogTitle>
            <DialogDescription>
              {agentName} will be permanently deleted, and any phone numbers assigned to it will stop answering calls.
            </DialogDescription>
          </DialogHeader>
          <Field>
            <FieldLabel>Type “{agentName}” to confirm</FieldLabel>
            <Input value={confirmation} onChange={(event) => setConfirmation(event.target.value)} />
          </Field>
        </DialogBody>
        <DialogFooter className="justify-between">
          <DialogNotice className="text-danger-fg" icon={<TriangleAlertIcon radius="2" />}>
            This cannot be undone
          </DialogNotice>
          <div className="flex gap-2">
            <DialogClose render={<Button variant="transparent" />}>Cancel</DialogClose>
            <DialogClose render={<Button variant="danger" />} disabled={confirmation !== agentName}>
              Delete agent
            </DialogClose>
          </div>
        </DialogFooter>
      </DialogContent>
    </Dialog>
  );
}

Multi-step

DialogStepBody slides each step in from the direction of travel and animates the height between steps. Keep progress and the footer actions in place.

import { useState } from "react";
import {
  Button,
  Dialog,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogStepBody,
  DialogTitle,
  DialogTrigger,
  Field,
  FieldLabel,
  Fieldset,
  FieldsetLegend,
  Input,
  List,
  ListItem,
  RadioCard,
  RadioGroup,
  Stepper,
  type DialogStepDirection,
} from "@smallest-inc/ui";

const steps = ["Details", "Voice", "Review"];

export default function DialogMultiStep() {
  const [step, setStep] = useState(0);
  const [direction, setDirection] = useState<DialogStepDirection>(1);
  const [name, setName] = useState("Support agent");
  const [voice, setVoice] = useState("warm");

  const goToStep = (nextStep: number) => {
    setDirection(nextStep > step ? 1 : -1);
    setStep(nextStep);
  };

  return (
    <Dialog
      onOpenChange={(open) => {
        if (open) {
          setStep(0);
          setDirection(1);
        }
      }}
    >
      <DialogTrigger render={<Button variant="secondary" />}>Create agent</DialogTrigger>
      <DialogContent>
        <DialogStepBody step={step} direction={direction}>
          {step === 0 ? (
            <div className="flex flex-col gap-6">
              <DialogHeader>
                <DialogTitle>Create agent</DialogTitle>
                <DialogDescription>Start with a name. You can change it later.</DialogDescription>
              </DialogHeader>
              <Fieldset>
                <FieldsetLegend className="sr-only">Agent details</FieldsetLegend>
                <Field>
                  <FieldLabel>Agent name</FieldLabel>
                  <Input value={name} onChange={(event) => setName(event.target.value)} />
                </Field>
              </Fieldset>
            </div>
          ) : null}

          {step === 1 ? (
            <div className="flex flex-col gap-6">
              <DialogHeader>
                <DialogTitle>Choose a voice</DialogTitle>
                <DialogDescription>Pick the delivery that matches how your agent should sound.</DialogDescription>
              </DialogHeader>
              <RadioGroup value={voice} onValueChange={setVoice}>
                <RadioCard value="warm" title="Warm" description="Friendly and reassuring for support calls." />
                <RadioCard value="clear" title="Clear" description="Measured and direct for product guidance." />
                <RadioCard value="bright" title="Bright" description="Energetic and expressive for outbound calls." />
              </RadioGroup>
            </div>
          ) : null}

          {step === 2 ? (
            <div className="flex flex-col gap-6">
              <DialogHeader>
                <DialogTitle>Review agent</DialogTitle>
                <DialogDescription>Confirm the details before creating your agent.</DialogDescription>
              </DialogHeader>
              <List>
                <ListItem>
                  <span className="w-24 shrink-0 text-sm text-fg-secondary">Name</span>
                  <span className="min-w-0 text-sm font-medium text-fg">{name || "Untitled agent"}</span>
                </ListItem>
                <ListItem>
                  <span className="w-24 shrink-0 text-sm text-fg-secondary">Voice</span>
                  <span className="min-w-0 text-sm font-medium text-fg capitalize">{voice}</span>
                </ListItem>
              </List>
            </div>
          ) : null}
        </DialogStepBody>
        <DialogFooter className="justify-between">
          <Stepper variant="ghost" count={steps.length} value={step} labels={steps} aria-label="Agent setup progress" />
          <div className="flex gap-2">
            {step === 0 ? (
              <DialogClose render={<Button variant="transparent" />}>Cancel</DialogClose>
            ) : (
              <Button variant="transparent" onClick={() => goToStep(step - 1)}>
                Back
              </Button>
            )}
            {step === steps.length - 1 ? (
              <DialogClose render={<Button />}>Create agent</DialogClose>
            ) : (
              <Button onClick={() => goToStep(step + 1)}>Continue</Button>
            )}
          </div>
        </DialogFooter>
      </DialogContent>
    </Dialog>
  );
}

Footer without separator

The footer has a top border by default. Pass separated={false} for short dialogs where the border adds nothing.

import {
  Button,
  Dialog,
  DialogBody,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
  Field,
  FieldLabel,
  Input,
} from "@smallest-inc/ui";

export default function DialogFooterExample() {
  return (
    <Dialog>
      <DialogTrigger render={<Button variant="secondary" />}>Rename agent</DialogTrigger>
      <DialogContent>
        <DialogBody className="flex flex-col gap-6 pb-3">
          <DialogHeader>
            <DialogTitle>Rename agent</DialogTitle>
            <DialogDescription>The new name shows in call logs and analytics.</DialogDescription>
          </DialogHeader>
          <Field>
            <FieldLabel>Agent name</FieldLabel>
            <Input defaultValue="Support agent" />
          </Field>
        </DialogBody>
        <DialogFooter separated={false}>
          <DialogClose render={<Button variant="transparent" />}>Cancel</DialogClose>
          <DialogClose render={<Button />}>Save</DialogClose>
        </DialogFooter>
      </DialogContent>
    </Dialog>
  );
}

Controlled

Pass open and onOpenChange to open the dialog from code, such as after a file is chosen or from a menu item.

import { useState } from "react";
import {
  Button,
  Dialog,
  DialogBody,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
} from "@smallest-inc/ui";

export default function DialogControlled() {
  const [open, setOpen] = useState(false);

  return (
    <>
      <Button variant="secondary" onClick={() => setOpen(true)}>
        Import contacts
      </Button>
      <Dialog open={open} onOpenChange={setOpen}>
        <DialogContent>
          <DialogBody>
            <DialogHeader>
              <DialogTitle>Import contacts</DialogTitle>
              <DialogDescription>
                1,240 contacts from contacts.csv will be added to the Outbound renewals campaign.
              </DialogDescription>
            </DialogHeader>
          </DialogBody>
          <DialogFooter>
            <Button variant="transparent" onClick={() => setOpen(false)}>
              Cancel
            </Button>
            <Button onClick={() => setOpen(false)}>Import contacts</Button>
          </DialogFooter>
        </DialogContent>
      </Dialog>
    </>
  );
}

Best practices

When to use

Use for a focused task or decision that blocks the page until it is completed or dismissed, such as “Create view” or “Rename agent”.
Use Drawer for supporting detail that can sit beside the page, Alert Dialog for a yes/no decision with no fields, and a full page for a long creation flow.

Behavior

Render footer actions with DialogClose render={<Button />} so every action closes the dialog; use open and onOpenChange only when code must open it or keep it open (validation, async save).
Pass showCloseButton for long or scrollable content and add pr-8 to DialogHeader so the title clears it. DialogBody scrolls; DialogFooter stays fixed.
For multi-step flows use DialogStepBody with step and direction (1 forward, -1 back), keep the Stepper and footer in place, and swap Cancel for Back after the first step.
Non-destructive dialogs dismiss with Escape or an outside click. For destructive work, name the object and keep the action disabled until the confirmation matches.

Content

Title and primary action use the same verb and object in sentence case: title “Delete agent”, action “Delete agent”, never “OK” or “Confirm”.
One primary Button per footer. Cancel is variant="transparent"; destructive actions are variant="danger" with a DialogIcon and a DialogNotice stating the consequence.
Pass separated={false} on DialogFooter only for short dialogs with one field.

Accessibility

Always include DialogTitle; add DialogDescription when the title alone does not explain the task. Both are announced on open.
Focus moves into the dialog, stays trapped while open and returns to the trigger on close.

PreviousCommand NextDrawer