Dialog

A focused task in a native modal, with the page behind it kept inert.

Interactive preview

Live specimenTry the component

Installation

Add editable source to an initialized React project. Set up antiflex/ui first if you are new here.

Terminal

npx antiflex-ui@0.1.0-alpha.2 add dialog

This site previews the latest workspace styles and motion. The published alpha keeps its released styles until the next npm release.

Usage

React

<Dialog>
  <DialogTrigger>Edit project</DialogTrigger>
  <DialogContent>
    <DialogHeader>
      <DialogTitle>Edit project</DialogTitle>
      <DialogDescription>Update your project details.</DialogDescription>
    </DialogHeader>
    <DialogBody>Project fields go here.</DialogBody>
    <DialogFooter><DialogClose>Cancel</DialogClose></DialogFooter>
  </DialogContent>
</Dialog>

API reference

All components forward native attributes, className, and refs to their underlying elements.

Prop	Type	Default
`Root: open / defaultOpen / onOpenChange`	`boolean / boolean / (open: boolean) => void`	`uncontrolled, closed`
`Content: size`	`sm (400px) \| md (512px) \| lg (640px)`	`md`
`Content: initialFocusRef / returnFocusRef`	`RefObject<HTMLElement \| null>`	`native initial focus / invoker`
`Content: dismissOnOutside`	`boolean`	`true`
`Content: onCancel / onClose`	`native dialog events`	`Escape requests close; close mirrors native state`
`Trigger / Close`	`ButtonProps, native button attributes/ref`	`primary / secondary`

Accessibility

Use for a task that warrants interruption; ordinary inline content should remain inline. Content is a native dialog opened with showModal(), not an open attribute or custom overlay. Provide one DialogTitle (or aria-label/aria-labelledby), an explicit close action, and optionally one short DialogDescription. Set aria-describedby="" for structured long content and focus a heading through initialFocusRef. The browser supplies top-layer modality and inert background; antiflex loops Tab/Shift+Tab, locks page scroll, and restores a connected visible invoker or returnFocusRef. Escape requests closing; preventDefault in onCancel cancels that request. Backdrop closing requires a pointer press and release outside; drags starting inside do not dismiss. Controlled open remains consumer-owned; ignoring onOpenChange keeps the modal open. Native method="dialog" forms and ref.close() request synchronization; controlled refusal reopens. Content stays mounted when closed, so fields persist unless the application resets them. Root is a provider without DOM/ref; Content ref targets HTMLDialogElement, Title h2, Description p, and layout parts divs. Do not pass open/id/role directly to Content, add positive tabindex, nest interactive triggers, or render multiple titles/descriptions per root. Nest complete roots for stacked dialogs. Modern browsers with native dialog support are required; no legacy polyfill or nonmodal mode is included.