Geist Design System

Modal

Display popup content that requires attention or provides additional information.

Default

Sticky

Single button

Disabled actions

Inset

Control initial focus

Best Practices

When to use

  • Use Modal when a decision must block the rest of the page. For persistent associated context where the underlying page stays readable, use Sheet on desktop or Drawer on mobile.
  • Confirm destructive actions in a Modal. Drawer and Sheet don’t fully dim the page, so they read as too soft for a delete or revoke.
  • Skip Modal for routine create flows that have a dedicated page; route to the page instead.

Behavior

  • Default focus to Cancel on any destructive Modal. Enter must never trigger the destructive action without a typed confirmation.
  • Allow Escape and outside-click to dismiss non-destructive Modals; gate dismissal on destructive ones with unsaved input.
  • Trap focus inside the Modal while it’s open and return focus to the trigger after close. Restore body scroll on the same tick the Modal unmounts.
  • For high-stakes destructive actions (delete production resource, rotate signing key, downgrade plan), gate the primary button on a typed match of the resource name.

Content

  • Modal.Title is a Title Case statement, never a question. Transfer Project is correct; Transfer Project? is wrong.
  • Modal.P body is sentence case, 1–3 sentences. State the consequence first, then any cascade.
  • Primary button is Verb + Noun and matches the title verb (Transfer Project title pairs with Transfer Project button). Never Confirm, OK, or a bare verb on a destructive primary.
  • Cancel literal stays Cancel. Acknowledgment-only Modals (after a key reveal, after a one-time-show) use Done, never OK or Close.
  • Close irreversible bodies with This cannot be undone.; close cascade-only bodies with Some effects cannot be undone.. Don’t claim full irreversibility for a partial cascade.
  • Pair the success toast verb 1:1 with the primary button: Delete Project button, Project deleted toast.

Accessibility

  • Set aria-labelledby to the Modal.Title id so screen readers announce the title on open.
  • Keep the Cancel button literally Cancel so screen-reader users hear a stable dismissal label across destructive flows.
  • After an error inside the Modal, keep focus inside so the user can retry; after success, return focus to the trigger.