Dialog

Installation

Copy editable source into an initialized application:

pnpm dlx @simurgh-ui/cli add dialog

For package consumption, import from the component subpath and load its optional recipe CSS:

React

import {
  Dialog,
  DialogTrigger,
  DialogPortal,
  DialogOverlay,
  DialogContent,
  DialogTitle,
  DialogDescription,
  DialogClose,
} from '@simurgh-ui/react/dialog';
import '@simurgh-ui/styles/dialog.css';

Vue

import {
  Dialog,
  DialogTrigger,
  DialogContent,
  DialogTitle,
  DialogDescription,
  DialogClose,
} from '@simurgh-ui/vue/dialog';
import '@simurgh-ui/styles/dialog.css';

Angular

import { DialogComponent } from '@simurgh-ui/angular/dialog';
import '@simurgh-ui/styles/dialog.css';

Omit the component stylesheet for fully headless styling. CLI-copied components use the local path written to simurgh.json and the copied application styles instead of these package imports.

Purpose

Default presentation: styled

The optional component stylesheet provides a complete default recipe, including visual hierarchy and interaction states. Consumers can override semantic tokens or omit the recipe.

Basic usage

Live component Dialog

Anatomy

Dialog, trigger, portal/overlay, content, title, description, and close. The title and description provide the accessible name and description. Escape closes the modal; Tab remains contained; focus returns to the opener.

State model

Controlled state remains the application’s source of truth and must be updated from every change event. Uncontrolled state reads its default only when the component mounts. Do not pass both forms of the same state at once.

Framework	Exact state contract and reset behavior
React	Controlled: `open` + `onOpenChange`. Uncontrolled: `defaultOpen`. Reset controlled state by assigning the initial value; reset uncontrolled state by changing a React `key`.
Vue	Controlled: `v-model:open` (`open` + `update:open`). Uncontrolled: `defaultOpen`. Reset the model ref to its initial value; reset uncontrolled state with a changed Vue `:key`.
Angular	Controlled two-way binding: `[(open)]` (`open` + `openChange`). Angular exposes no separate default input; initialize and reset the bound class field explicitly.

React

const initialOpen = false;
const [open, setOpen] = useState(initialOpen);
const [resetKey, setResetKey] = useState(0);

<Dialog open={open} onOpenChange={setOpen}>…</Dialog>
<button onClick={() => setOpen(initialOpen)}>Reset controlled</button>
<Dialog key={resetKey} defaultOpen={initialOpen}>…</Dialog>
<button onClick={() => setResetKey((key) => key + 1)}>Reset uncontrolled</button>

Vue

<script setup lang="ts">
import { ref } from 'vue';
const initial = false;
const state = ref(initial);
const resetKey = ref(0);
</script>

<Dialog v-model:open="state">…</Dialog>
<button @click="state = initial">Reset controlled</button>
<Dialog :key="resetKey" :defaultOpen="initial">…</Dialog>
<button @click="resetKey++">Reset uncontrolled</button>

Angular

initial = false;
open = this.initial;
reset() { this.open = this.initial; }

<simurgh-dialog [(open)]="open">…</simurgh-dialog>
<button type="button" (click)="reset()">Reset</button>

Use the recipe classes for the default modal treatment, or remove them and style the semantic parts directly.

Examples

<Dialog><DialogTrigger>Edit profile</DialogTrigger><DialogPortal><DialogOverlay /><DialogContent><DialogTitle>Profile</DialogTitle><DialogDescription>Change public details.</DialogDescription><DialogClose>Done</DialogClose></DialogContent></DialogPortal></Dialog>

<Dialog><DialogTrigger>Edit profile</DialogTrigger><DialogContent aria-label="Profile"><p>Change public details.</p><DialogClose>Done</DialogClose></DialogContent></Dialog>

<simurgh-dialog #dialog><button trigger (click)="dialog.show()">Edit profile</button><h2>Profile</h2><p>Change public details.</p><button (click)="dialog.close()">Done</button></simurgh-dialog>

Real-world example: async profile submission

Keep the dialog controlled while saving so success can close it and failure can leave the form open. Disable repeated submission and announce the result without moving focus unexpectedly.

const [open, setOpen] = useState(false);
const [saving, setSaving] = useState(false);
const [message, setMessage] = useState('');
async function submitProfile(event: FormEvent<HTMLFormElement>) {
  event.preventDefault();
  setSaving(true);
  setMessage('');
  try {
    await saveProfile(new FormData(event.currentTarget));
    setOpen(false);
  } catch {
    setMessage('Could not save the profile. Try again.');
  } finally {
    setSaving(false);
  }
}
<Dialog open={open} onOpenChange={setOpen}>
  …
  <form onSubmit={submitProfile}>
    <Button type="submit" loading={saving}>
      Save
    </Button>
    <p aria-live="polite">{message}</p>
  </form>
  …
</Dialog>;

Vue uses v-model:open="open" and Angular uses [(open)]="open"; apply the same pending, error, and close-on-success flow in the component script or class.

Keyboard interactions

These keys describe behavior implemented by the adapters. Native Tab, Enter, and Space behavior still applies to descendant links, buttons, and form controls unless the component overrides it.

Concern / keys	Behavior
Focus entry and exit (Tab / Shift+Tab)	Tab enters the open dialog and cycles within it; closing restores the trigger.
Navigation and activation	Enter or Space activates the focused control.
Escape	Closes the dialog and restores trigger focus.
RTL differences	No RTL-specific key mapping.
Typeahead	Not supported.

Accessibility

Preserve the documented composition and accessible names when wrapping or restyling this component. See accessibility and RTL guidance for keyboard, focus, labeling, and directionality requirements.

API surface

React exports: Dialog, DialogTrigger, DialogPortal, DialogOverlay, DialogContent, DialogTitle, DialogDescription, DialogClose
Vue exports: Dialog, DialogTrigger, DialogContent, DialogTitle, DialogDescription, DialogClose
Angular exports: DialogComponent

Import these public symbols from the component subpath shown in Installation. Framework-specific props, events, slots, directives, methods, defaults, and native-attribute behavior belong in the API tables on this page; use the linked source only to verify the current implementation.

React API reference

React

An inherited-attributes entry means the component accepts the complete named React native interface, including its event handlers and ARIA and data attributes. Remaining attributes are forwarded to the rendered element unless the component behavior described on this page overrides them.

`Dialog`

Complete props type: PropsWithChildren<OpenProps>.

Prop	Type	Default / requirement
`children`	`ReactNode`	`undefined`
`defaultOpen`	`boolean`	`undefined`
`onOpenChange`	`(open: boolean) => void`	`undefined`
`open`	`boolean`	`undefined`

`DialogTrigger`

Inherited attributes: ButtonHTMLAttributes<HTMLButtonElement> & RefAttributes<HTMLButtonElement>.

Prop	Type	Default / requirement
`children`	`ReactNode`	`undefined`
`ref`	`Ref<HTMLButtonElement> \| undefined`	`undefined`

`DialogPortal`

Complete props type: { children?: ReactNode; }.

Prop	Type	Default / requirement
`children`	`ReactNode`	`undefined`

`DialogOverlay`

Inherited attributes: HTMLAttributes<HTMLDivElement> & RefAttributes<HTMLDivElement>.

Prop	Type	Default / requirement
`children`	`ReactNode`	`undefined`
`ref`	`Ref<HTMLDivElement> \| undefined`	`undefined`

`DialogContent`

Inherited attributes: HTMLAttributes<HTMLDivElement> & RefAttributes<HTMLDivElement>.

Prop	Type	Default / requirement
`children`	`ReactNode`	`undefined`
`ref`	`Ref<HTMLDivElement> \| undefined`	`undefined`

`DialogTitle`

Inherited attributes: HTMLAttributes<HTMLHeadingElement>.

Prop	Type	Default / requirement
`children`	`ReactNode`	`undefined`

`DialogDescription`

Inherited attributes: HTMLAttributes<HTMLParagraphElement>.

Prop	Type	Default / requirement
`children`	`ReactNode`	`undefined`

`DialogClose`

Inherited attributes: ButtonHTMLAttributes<HTMLButtonElement> & RefAttributes<HTMLButtonElement>.

Prop	Type	Default / requirement
`children`	`ReactNode`	`undefined`
`ref`	`Ref<HTMLButtonElement> \| undefined`	`undefined`

Vue API reference

Vue

Boolean props without explicit defaults use Vue’s false default. Undeclared attributes follow the fallthrough behavior stated for each component.