FormDialog

FormDialog combines VDialog and VForm into a single component for form-in-dialog flows. It provides built-in cancel / confirm buttons, form validation, an optional content loading mask, and a fullscreen toggle in the title area.

Basic Usage

Basic form dialog with form-items and on-submit.

Custom Content

Use the content slot to render extra content below the built-in form.

Fullscreen Toggle

Set with-full-screen to show a fullscreen toggle button in the dialog title.

Complete example

Combine v-model, submit-callback, footer slots, on-after-close, and the exposed clearValidate() method in one dialog workflow.

Current form data	{ "name": "", "email": "", "role": "", "remark": "" }
Last validated payload	No validated payload yet
Status

vue

<template>
  <div class="form-dialog-complete">
    <div class="toolbar">
      <el-button type="primary" @click="visible = true">
        Open complete example
      </el-button>
      <el-button :disabled="!lastValidated" @click="restoreLastValidated">
        Restore last validated
      </el-button>
    </div>

    <el-descriptions :column="1" border>
      <el-descriptions-item label="Current form data">
        <pre class="state-block">{{ currentFormDataText }}</pre>
      </el-descriptions-item>
      <el-descriptions-item label="Last validated payload">
        <pre class="state-block">{{ lastValidatedText }}</pre>
      </el-descriptions-item>
      <el-descriptions-item label="Status">
        <div class="status-row">
          <el-tag type="success">submitted {{ submitCount }} times</el-tag>
          <el-tag type="info">closed {{ closeCount }} times</el-tag>
        </div>
      </el-descriptions-item>
    </el-descriptions>

    <form-dialog
      ref="formDialogRef"
      v-model:dialog-visible="visible"
      v-model="formData"
      title="Create team member"
      width="680px"
      :form-items="formItems"
      :submit-callback="handleValidated"
      :on-submit="handleSubmit"
      :on-after-close="handleAfterClose"
    >
      <template #content>
        <el-alert
          type="info"
          show-icon
          :closable="false"
          title="Try submitting with an empty email first, then use the footer tools to fill the form or clear the email validation state."
        />
      </template>

      <template #leftButtons="{ formData: dialogFormData }">
        <el-button @click="fillDraft(dialogFormData)">Fill draft</el-button>
      </template>

      <template #middleButtons="{ changeLoadingStatus }">
        <el-button @click="simulateCheck(changeLoadingStatus)">
          Manual loading
        </el-button>
        <el-button @click="clearEmailValidate">Clear email error</el-button>
      </template>
    </form-dialog>
  </div>
</template>

<script lang="ts" setup>
import { computed, ref } from 'vue'
import { ElMessage } from 'element-plus'

interface FormState {
  name: string
  email: string
  role: string
  remark: string
}

interface FormDialogExpose {
  clearValidate: (field?: string | string[]) => void
}

const createFormData = (): FormState => ({
  name: '',
  email: '',
  role: '',
  remark: '',
})

const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))

const visible = ref(false)
const submitCount = ref(0)
const closeCount = ref(0)
const formData = ref<FormState>(createFormData())
const lastValidated = ref<FormState | null>(null)
const formDialogRef = ref<FormDialogExpose>()

const formItems = ref([
  {
    prop: 'name',
    label: 'Name',
    element: 'el-input',
    required: true,
    attrs: {
      placeholder: 'Enter a name',
    },
  },
  {
    prop: 'email',
    label: 'Email',
    element: 'el-input',
    required: true,
    rules: [
      { type: 'email', message: 'Please enter a valid email', trigger: 'blur' },
    ],
    attrs: {
      placeholder: 'Enter an email address',
    },
  },
  {
    prop: 'role',
    label: 'Role',
    element: 'el-select',
    required: true,
    attrs: {
      placeholder: 'Select a role',
    },
    options: [
      { label: 'Developer', value: 'developer' },
      { label: 'Designer', value: 'designer' },
      { label: 'Manager', value: 'manager' },
    ],
  },
  {
    prop: 'remark',
    label: 'Remark',
    element: 'el-input',
    attrs: {
      type: 'textarea',
      rows: 3,
      placeholder: 'Optional note',
    },
  },
])

const currentFormDataText = computed(() =>
  JSON.stringify(formData.value, null, 2)
)
const lastValidatedText = computed(() => {
  return lastValidated.value
    ? JSON.stringify(lastValidated.value, null, 2)
    : 'No validated payload yet'
})

const handleValidated = (data: FormState) => {
  lastValidated.value = { ...data }
}

const handleSubmit = async (data: FormState) => {
  await sleep(1000)
  submitCount.value += 1
  visible.value = false
  ElMessage.success(`Saved ${data.name}`)
}

const handleAfterClose = () => {
  closeCount.value += 1
}

const fillDraft = (target: FormState) => {
  target.name = 'Ada Lovelace'
  target.email = 'ada@example.com'
  target.role = 'developer'
  target.remark = 'Filled from the leftButtons slot.'
}

const clearEmailValidate = () => {
  formDialogRef.value?.clearValidate('email')
  ElMessage.info('Email validation cleared')
}

const simulateCheck = async (changeLoadingStatus: (flag: boolean) => void) => {
  changeLoadingStatus(true)
  await sleep(800)
  changeLoadingStatus(false)
  ElMessage.info('Manual loading finished')
}

const restoreLastValidated = () => {
  if (!lastValidated.value) return
  formData.value = { ...lastValidated.value }
}
</script>

<style scoped>
.form-dialog-complete {
  width: 100%;
}

.toolbar {
  display: flex;
  gap: 12px;
  flex-wrap: wrap;
  margin-bottom: 16px;
}

.status-row {
  display: flex;
  gap: 12px;
  flex-wrap: wrap;
}

.state-block {
  margin: 0;
  white-space: pre-wrap;
  word-break: break-word;
  font-size: 12px;
  line-height: 1.5;
}
</style>

Behavior Notes

dialog-visible / v-model:dialog-visible controls dialog visibility.
model-value / v-model binds the form data object managed by the inner VForm.
Clicking the confirm button validates the inner form first. After validation succeeds, submit-callback runs before on-submit.
While on-submit is running, the component enables the internal loading state for the confirm button. When auto-loading is true, that loading state is cleared automatically after the awaited callback finishes.
on-after-close runs whenever the wrapped dialog finishes closing and also resets the internal loading state.
with-full-screen only shows the toggle icon. The fullscreen state itself is managed internally by FormDialog.
mode='readonly' passes disabled to the inner VForm, making the generated form items non-editable. mode='edit' keeps them editable.
mode='readonly' only affects the generated form fields. Footer buttons still follow show-footer, show-sure-button, and show-cancle-button.

API

FormDialog Attributes

Name	Description	Type	Default
title	dialog title	`string`	`'编辑弹窗'`
dialog-visible / v-model:dialog-visible	dialog visibility	`boolean`	false
model-value / v-model	form data object	`object`	`{}`
dialog-props	extra props object forwarded to the inner `VDialog`, merged down to the underlying `ElDialog`	`object`	`{}`
form-items	form item configuration passed to `VForm`	`array`	[]
width	dialog width	`string` / `number`	`'70%'`
label-width	form label width	`string` / `number`	`'160px'`
label-position	form label position	`enum`	`'right'`
content-loading	show a loading mask over the dialog body content area	`boolean`	false
show-footer	show the built-in footer	`boolean`	true
show-sure-button	show the confirm button	`boolean`	true
show-cancle-button	show the cancel button	`boolean`	true
disabled-sure-button	disable the confirm button	`boolean`	false
cancel-text	cancel button text, falls back to the locale message when unset	`string`	—
sure-text	confirm button text, falls back to the locale message when unset	`string`	—
with-full-screen	show the fullscreen toggle icon in the title area	`boolean`	false
auto-loading	automatically clear loading after awaited `on-submit` completes	`boolean`	true
on-submit	awaited callback invoked after validation succeeds	`function`	—
submit-callback	callback invoked after validation succeeds and before `on-submit`	`function`	—
on-after-close	callback invoked after the dialog closes	`function`	—
mode	control whether the generated form is editable or readonly	`enum`	`'edit'`

FormDialog Events

Name	Description	Type
update:dialog-visible	triggered when dialog visibility changes	`function`
update:model-value	triggered when form data changes	`function`

FormDialog Slots

Name	Description
title	custom dialog title; slot props: `{ close, titleId, titleClass }`
header	extra content rendered at the top of the dialog body, below the title area
formFooter	custom content rendered after the generated form items
content	custom content rendered below the form
leftButtons	custom buttons rendered on the left side of the footer; slot props: `{ loading, formData, changeLoadingStatus }`
middleButtons	custom buttons rendered between the cancel and confirm buttons; slot props: `{ loading, formData, changeLoadingStatus }`

Exposes

Name	Description	Type
clearValidate	clear form validation state	`function`

Source

Docs

VForm

VButton

FormDialog ​

Basic Usage ​

Custom Content ​

Fullscreen Toggle ​

Complete example ​

Behavior Notes ​

API ​

FormDialog Attributes ​

FormDialog Events ​

FormDialog Slots ​

Exposes ​

Source ​