Geist Design System

Modal

Display popup content that requires attention or provides additional information.

Default

Sticky

Single button

Disabled actions

Inset

Control initial focus

Focus an input on open

Mobile sheet with inputs

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.