Form Dialog

ProNew

A dialog that holds a form: pending and error states, a guard against closing with unsaved input, and an imperative promise API (await openForm(...)) that resolves with the submitted values or null.

Customize

This item has no props to tune. Use the lens above to change theme, density, direction and more.

Guide and examples

Installation


pnpm dlx shadcn@latest add @tealmac-pro/form-dialog

Usage

Controlled, when the dialog is part of your page state:

Imperative, when a handler needs the answer: wrap the app once in FormDialogProvider, then

Exports

Export	Description
`FormDialog`	Controlled dialog with a form, pending and error states, and a discard guard.
`FormDialogProvider`, `useFormDialog`	The promise API: `await openForm(request)` resolves with the values or `null`.

Props

Prop (`FormDialog`)	Type	Description
`open`, `onOpenChange`	`boolean`, `(open) => void`	Controlled state.
`title`, `description`	`ReactNode`	The title is the accessible name; a missing description is replaced by a screen-reader-only one.
`onSubmit`	`() => void \| Promise<void>`	Throw to keep the dialog open and show the message.
`dirty`	`boolean`	Ask "Discard changes?" on close.
`submitLabel`, `pendingLabel`, `cancelLabel`	`string`	Button text.

Accessibility

Built on the Radix dialog: focus moves into the dialog, is trapped there and returns to the trigger on close; Escape closes it.
Enter submits from any field because the fields sit in a real form. The submit button shows a spinner and the form sets aria-busy; Cancel and Escape are ignored while the submit runs.
A failed submit renders a role="alert" message without moving focus away from the field the person was in.
The discard question is an alertdialog, so it takes focus and is announced; "Keep editing" is the default action.

Testing

The component ships with a Testing Library test (form-dialog.test.tsx) that covers: its main behaviour, the keyboard path and the error or empty states.

Guide and examples

Installation


pnpm dlx shadcn@latest add @tealmac-pro/form-dialog

Usage

Controlled, when the dialog is part of your page state:

Imperative, when a handler needs the answer: wrap the app once in FormDialogProvider, then

Exports

Export	Description
`FormDialog`	Controlled dialog with a form, pending and error states, and a discard guard.
`FormDialogProvider`, `useFormDialog`	The promise API: `await openForm(request)` resolves with the values or `null`.

Props

Prop (`FormDialog`)	Type	Description
`open`, `onOpenChange`	`boolean`, `(open) => void`	Controlled state.
`title`, `description`	`ReactNode`	The title is the accessible name; a missing description is replaced by a screen-reader-only one.
`onSubmit`	`() => void \| Promise<void>`	Throw to keep the dialog open and show the message.
`dirty`	`boolean`	Ask "Discard changes?" on close.
`submitLabel`, `pendingLabel`, `cancelLabel`	`string`	Button text.

Accessibility

Built on the Radix dialog: focus moves into the dialog, is trapped there and returns to the trigger on close; Escape closes it.
Enter submits from any field because the fields sit in a real form. The submit button shows a spinner and the form sets aria-busy; Cancel and Escape are ignored while the submit runs.
A failed submit renders a role="alert" message without moving focus away from the field the person was in.
The discard question is an alertdialog, so it takes focus and is announced; "Keep editing" is the default action.

Testing

The component ships with a Testing Library test (form-dialog.test.tsx) that covers: its main behaviour, the keyboard path and the error or empty states.