Components/ModalForm

ModalForm

A form that edits one record in a dialog.

VerifiedSince 0.9.2

Usage

Basic

Each open edits a copy of initialValues; the dialog closes once the submit succeeds, and asks before closing on unsaved changes.

Loading demo...

The footer slot receives formId, submitting and cancel; the submit button points at the form with form, so Enter and a click submit alike.

<TxModalForm v-model="open" :initial-values="member" @submit="save">
  <template #default="{ model }">…</template>
  <template #footer="{ formId, submitting, cancel }">
    <TxButton variant="danger" :disabled="submitting" @click="remove">Delete</TxButton>
    <TxButton :disabled="submitting" @click="cancel">Cancel</TxButton>
    <TxButton variant="primary" native-type="submit" :form="formId" :loading="submitting">Save</TxButton>
  </template>
</TxModalForm>

Best Practices

  • Keep it to a few fields. Use TxDrawerForm for long forms, forms that scroll, or forms read against the page.
  • Return a promise from @submit. Return false, throw, or call setErrors(), and the dialog stays open.
  • Modal forms do not autosave. To save as the user edits, put a TxForm with autosave in a TxDrawer.
  • In a custom footer, close with the slot's cancel: like Escape, it asks first.
  • Outside English, pass submitText, cancelText, messages.leaveConfirm, and modalProps.closeLabel to name the close button.

API Reference

Props

The TxForm props below apply too: the dialog builds model from initialValues, and autosave does not apply.

PropTypeDefaultDescription
modelValuebooleanrequiredShows the dialog. Use with v-model.
titlestring''Dialog title.
widthstring'480px'Dialog width.
initialValuesFormValues-The values the form opens with. Each open edits a copy, so the parent's values change only when the parent changes them.
submitTextstring'Save'Text of the submit button.
cancelTextstring'Cancel'Text of the cancel button.
modalPropsRecord<string, unknown>-Any other TxModal prop, such as surface or fullscreen. Closing is asked of the form, not of beforeClose.
idstringgeneratedThe form's id, and the prefix of every field id.
rulesFormRules-Form-level rules keyed by field path.
schemaFormStandardSchema-A Standard Schema v1 validator checked against the whole model; issues with no matching field are listed in the error summary.
layout'auto' | 'side' | 'stacked' | 'inline''auto'Field layout.
labelPosition'left' | 'right' | 'top'-Older spelling of layout.
labelAlign'start' | 'end''end'Label alignment in the side column.
labelWidthstring | number16emWidest the side label column may grow; numbers are in pixels.
requiredMark'asterisk' | 'optional' | 'none''asterisk'Marks required fields with an asterisk, optional fields with messages.optional, or neither.
validateOn'blur' | 'submit''blur'When the first message appears: on leaving a changed field, or on the first submit.
messagesPartial<FormMessages>-Overrides the built-in text.
size'small' | 'medium' | 'large''medium'Size of the controls inside; the dialog width is width.
disabledbooleanfalseDisables the controls inside that read the form, and blocks submit.
readonlybooleanfalseShows the values as a record: controls can be focused and copied, not changed; no field is marked required.
reconcileFormReconcile-Decides what model holds when fetched values reach fields the user changed.
persistboolean | FormPersistOptionsfalseKeeps what the user typed under id; true takes the defaults.
leaveConfirmFormLeaveConfirm | falsehost's, then window.confirmAsked before leaving with changes no draft holds; false never asks.
onSubmit(values: FormValues, event?: Event) => unknown-Called once every check passes; the dialog stays open until a returned promise settles. @submit binds it.

Events

EventPayloadDescription
update:modelValue(value: boolean)The dialog opens or closes.
submit-success(values: FormValues)The submit went through; the dialog closes next.
validate(valid: boolean)As on TxForm.
persist-error(error: unknown)As on TxForm.

Slots

SlotPropsDescription
default{ model, dirty, valid, submitting, submitted, errors, rootError }The form items. model is the copy this open edits.
footer{ formId, submitting, cancel }Replaces the cancel and submit buttons.

Exposed Methods

NameTypeDescription
formTxForm | nullThe form inside while the dialog is open, with every TxForm method; null while it is closed.
cancel() => Promise<void>Closes as Cancel does: the form first asks about changes it would lose.

Overview

  • Each open builds model from a copy of initialValues and makes it the baseline. Closing unmounts the form with the dialog, so edits never carry over to the next open.
  • When initialValues changes while the dialog is open, as when a record finishes loading, it becomes the saved state: untouched fields take the new values, and fields the user changed keep their edits.
  • Escape, the mask, the close button and Cancel all go through the form's confirmLeave(), which asks only about changes no draft holds. A running submit cannot be closed.
  • Escape with focus inside a TxForm does not reach this path (see the Modal focus rule), so it asks nothing.
  • A submit that goes through emits submit-success, then closes.
  • The footer sits outside the <form>, and the submit button reaches it through form: Enter in a field and a click make the same submit with the same checks.

Technologies

  • Built from TxModal and TxForm, with beforeClose wired to the form's confirmLeave(). Opening, copying and closing share form/src/use-overlay-form.ts with TxDrawerForm.
  • Source: packages/tuffex/packages/components/src/modal-form/.
查看源码
packages/tuffex/packages/components/src/modal-form/index.ts