Skip to content
fuji-ui
Component

Modal

Dialog and AlertDialog are both modal overlays, wrapping Base UI. AlertDialog is for blocking confirmations that require an explicit choice.

Dialog

  • Content takes mobileBehavior: dialog | sheet | fullscreen, implemented with CSS max-sm: variants

Alert dialog (destructive confirmation)

When to use

  • The user must finish or explicitly dismiss a task before returning to the page (edit forms, confirmations, focused workflows).
  • AlertDialog specifically: destructive or irreversible actions that need an explicit yes/no, not a passive notice.

When not to use

  • Non-blocking status or a short message - use Toast or Notification instead.
  • Content the user should be able to reference alongside the page - use Drawer or Popover instead.
  • A simple yes/no that isn't destructive - a plain Dialog with two buttons is lighter than AlertDialog's stricter close semantics.

Keyboard

KeyAction
EscapeCloses the dialog (AlertDialog can be configured to block this for critical flows).
Tab / Shift+TabCycles focus within the dialog only - focus is trapped while open.
Enter / SpaceActivates the focused button, including Trigger and Close.

Mobile behavior

  • mobileBehavior="dialog" (default): stays a centered card at every width - use for short content that doesn't benefit from more room.
  • mobileBehavior="sheet": centered dialog on desktop, becomes a bottom-anchored full-width sheet under 640px - use for forms and taller content on mobile.
  • mobileBehavior="fullscreen": centered dialog on desktop, becomes a fully fullscreen view under 640px - use for complex, multi-step, or scroll-heavy content on mobile.
  • All three are pure CSS (max-sm: variants), so there's no layout flash or JS viewport check on first paint.

Accessibility notes

  • Base UI applies role="dialog" (or role="alertdialog" for AlertDialog), aria-modal, and wires Dialog.Title/Dialog.Description to aria-labelledby/aria-describedby automatically.
  • Focus moves into the dialog on open and returns to the trigger on close - verified by tabbing through Dialog.Trigger, opening, and closing with Escape.
  • The backdrop is inert to screen readers and pointer events outside the dialog while open.

Common mistakes

  • Omitting Dialog.Description for a form-heavy dialog - screen reader users get a title but no context for what they're editing.
  • Using Dialog for a destructive action instead of AlertDialog - Dialog closes on outside click/Escape by default, which is exactly wrong for "delete this forever."
  • Nesting a second modal dialog inside a dialog - stack Drawer or Popover instead if you need a secondary surface.

Known limitations

  • No built-in scroll-lock exception for iOS Safari's rubber-band scroll; verify manually on longer dialog content.

Related components

DrawerPopoverToast

Dialog.Content props

mobileBehavior"dialog"
"dialog" | "sheet" | "fullscreen"

How the dialog presents under the sm: breakpoint. CSS-driven, no JS viewport check.

hideCloseButtonfalse
boolean

Hides the built-in top-right close button.

classNameNone
string

Extra classes merged onto the popup surface.

CriterionStatusNote
Keyboard supportSupportedEscape closes; Tab/Shift+Tab cycle within a focus trap.
Focus managementSupportedFocus enters on open, returns to the trigger on close.
Screen reader labelsSupportedrole="dialog"/"alertdialog", aria-modal, and Title/Description wiring via Base UI.
Reduced motionSupportedprefers-reduced-motion: reduce zeroes all Fuji transition durations globally.
Reduced transparencySupportedprefers-reduced-transparency: reduce flattens Glass to opaque surfaces (portals included).
RTL layoutPartialLogical flex/grid gap works under dir="rtl"; directional chevrons are not yet mirrored.

API reference

open / defaultOpenNone
boolean

Controlled or initial overlay state.

mobileBehavior"dialog"
dialog | sheet | fullscreen

Narrow-screen presentation.

hideCloseButtonfalse
boolean

Hides the bare X dismiss control.

classNameNone
string

Additional classes applied to the component root.