cancelLabel | LocalizedMessage | — | Label of the cancel Button. |
children | ReactNode | — | The fields: Field, Fieldset, Select, Combobox, NumberField, TextArea, DateInput, Checkbox (or CheckboxGroup), CheckboxCards, RadioGroup, RadioCards, SegmentedControl, DurationField, FileUpload, or Slider. Not Switch: a form has a Save, so no change applies on its own (ADR 0023, decision 5). They sit in a column inside the dialog's scrolling body, which is the form.
Give every field a name: only named controls count toward unsaved edits and the form data. |
discard | FormDialogDiscardCopy | — | Copy of the unsaved-changes prompt. |
onSubmit | (event: FormEvent<HTMLFormElement>) => FormDialogSubmitOutcome | PromiseLike<FormDialogSubmitOutcome> | — | Called when the form submits, after the block ignores a repeat submit and prevents the native navigation. Validate
here. Return {@link FormDialogSubmitResult.Invalid} (or resolve to it) to keep the dialog open after a failed
validation, with invalid or errorSummary set so focus moves to the first invalid field. Return nothing, or
{@link FormDialogSubmitResult.Saved}, to close. Return a promise to hold the dialog open with the submit Button
loading until it settles. A rejected promise keeps the dialog open and is not rethrown: report it from the handler
and pass errorSummary.
@param event - The submit event; read the values from new FormData(event.currentTarget) |
submitLabel | LocalizedMessage | — | Label of the submit Button. |
title | LocalizedMessage | — | Heading that names the dialog. Always visible. |
className | string | — | Classes appended to the dialog surface. Put overrides in @layer chroma.overrides. |
defaultOpen | boolean | false | Initial open state when uncontrolled. |
description | LocalizedMessage | — | Supporting text under the title. Describes the dialog. |
dirty | boolean | — | Whether the form has unsaved edits. Omit it to compare the form's named controls with their values when the
dialog opened. Pass it when the edits live outside the form's controls, or when a control fills in after open. |
errorFocus | FormErrorFocus | FormErrorFocus.FirstInvalid | Where focus goes after a submit attempt ends with the form invalid. |
errorSummary | LocalizedMessage | — | Copy for a form-level error summary, announced when it appears. Clear it by passing undefined. |
invalid | boolean | — | Whether the form is invalid, which decides if a submit attempt moves focus. Defaults to whether errorSummary is
set. Pass it when per-field errors exist without a summary. |
onOpenChange | ((open: boolean, details: DialogOpenChangeDetails) => void) | — | Called once per open or close request: trigger press, cancel press (close-press), Escape (close-request), and
a saved submit (form-submit). A backdrop press never closes the dialog. A cancelable request is vetoed with
details.cancel(). A close request on a form with unsaved edits, or while a submit is pending, never reaches this:
the first asks the person to discard, the second is held.
@param open - The requested open state
@param details - Change metadata |
open | boolean | — | Controlled open state. Pair with {@link FormDialogProps.onOpenChange}. |
pendingLabel | LocalizedMessage | — | Name of the submit Button while a submit is pending, such as "Saving". Omit it to keep submitLabel as the name. |
ref | Ref<HTMLDialogElement> | — | Ref to the rendered dialog element. |
requiredHint | LocalizedMessage | — | One line above the fields that explains the required-field marker, for example "Fields marked with * are
required". The marker itself is drawn by each required Field's Label. Say it once here, never on each field. It is
the same line FormLayoutStandard calls requiredHint. |
scrollRegionLabel | LocalizedMessage | — | Name of the body's scroll region when it overflows and becomes focusable. |
size | FormDialogSize | FormDialogSize.Medium | Inline size from the --dialog-width-* tokens. |
trigger | DialogControlElement | — | One Button or Link that opens the dialog. Omit it when the caller controls open. |