Form

Form component enhanced based on Element Plus Form.

Form consists of input, radio, select, checkbox and so on. With form, you can collect, verify and submit data.

TIP

The component has been upgraded with a flex layout to replace the old float layout.

Basic Usage

It includes all kinds of input items, such as input, select, radio, checkbox, date-picker, time-picker, and switch.

Use the items prop to define form structure in a configuration-driven way, or use bk-form-item components to define form items manually. Each form item supports configuration options such as prop, label, and related field attributes.

Activity name

Activity zone

please select your zone

Activity time

-

Instant delivery

Activity type

Online activities Promotion activities Offline activities Simple brand exposure

Resources

SponsorVenue

Activity form

Activity name

Activity zone

please select your zone

Activity time

-

Instant delivery

Activity type

Online activitiesPromotion activitiesOffline activitiesSimple brand exposure

Resources

SponsorVenue

Activity form

<template>
  <bk-form :model="form" label-width="auto" style="max-width: 600px">
    <bk-form-item label="Activity name">
      <el-input v-model="form.name" />
    </bk-form-item>
    <bk-form-item label="Activity zone">
      <el-select v-model="form.region" placeholder="please select your zone">
        <el-option label="Zone one" value="shanghai" />
        <el-option label="Zone two" value="beijing" />
      </el-select>
    </bk-form-item>
    <bk-form-item label="Activity time">
      <el-col :span="11">
        <el-date-picker
          v-model="form.date1"
          type="date"
          placeholder="Pick a date"
          style="width: 100%"
        />
      </el-col>
      <el-col :span="2" class="text-center">
        <span class="text-gray-500">-</span>
      </el-col>
      <el-col :span="11">
        <el-time-picker v-model="form.date2" placeholder="Pick a time" style="width: 100%" />
      </el-col>
    </bk-form-item>
    <bk-form-item label="Instant delivery">
      <el-switch v-model="form.delivery" />
    </bk-form-item>
    <bk-form-item label="Activity type">
      <el-checkbox-group v-model="form.type">
        <el-checkbox value="Online activities" name="type"> Online activities </el-checkbox>
        <el-checkbox value="Promotion activities" name="type"> Promotion activities </el-checkbox>
        <el-checkbox value="Offline activities" name="type"> Offline activities </el-checkbox>
        <el-checkbox value="Simple brand exposure" name="type"> Simple brand exposure </el-checkbox>
      </el-checkbox-group>
    </bk-form-item>
    <bk-form-item label="Resources">
      <el-radio-group v-model="form.resource">
        <el-radio value="Sponsor">Sponsor</el-radio>
        <el-radio value="Venue">Venue</el-radio>
      </el-radio-group>
    </bk-form-item>
    <bk-form-item label="Activity form">
      <el-input v-model="form.desc" type="textarea" />
    </bk-form-item>
    <bk-form-item>
      <bk-button type="primary" @click="onSubmit">Create</bk-button>
      <bk-button>Cancel</bk-button>
    </bk-form-item>
  </bk-form>
  <el-divider></el-divider>
  <bk-form :model="form" :items="items" label-width="auto" style="max-width: 600px">
    <bk-form-item>
      <bk-button type="primary" @click="onSubmit">Create</bk-button>
      <bk-button>Cancel</bk-button>
    </bk-form-item>
  </bk-form>
</template>

<script lang="ts" setup>
import { reactive } from "vue"
import type { FormItemCtx } from "vue-business-kit"

const items: FormItemCtx[] = [
  {
    label: "Activity name",
    type: "input",
    prop: "name"
  },
  {
    label: "Activity zone",
    type: "select",
    prop: "region",
    componentProps: {
      placeholder: "please select your zone"
    },
    children: [
      { label: "Zone one", value: "shanghai" },
      { label: "Zone two", value: "beijing" }
    ]
  },
  {
    label: "Activity time",
    type: "date-picker",
    prop: "date1",
    componentProps: {
      type: "datetimerange",
      placeholder: "Pick a date",
      style: { width: "100%" }
    }
  },
  {
    label: "Instant delivery",
    type: "switch",
    prop: "delivery"
  },
  {
    label: "Activity type",
    type: "checkbox-group",
    prop: "type",
    children: [
      { label: "Online activities", value: "Online activities" },
      { label: "Promotion activities", value: "Promotion activities" },
      { label: "Offline activities", value: "Offline activities" },
      { label: "Simple brand exposure", value: "Simple brand exposure" }
    ]
  },
  {
    label: "Resources",
    type: "radio-group",
    prop: "resource",
    children: [
      { label: "Sponsor", value: "Sponsor" },
      { label: "Venue", value: "Venue" }
    ]
  },
  {
    label: "Activity form",
    type: "input",
    prop: "desc",
    componentProps: {
      type: "textarea"
    }
  }
]

// do not use same name with ref
const form = reactive({
  name: "",
  region: "",
  date1: "",
  date2: "",
  delivery: false,
  type: [],
  resource: "",
  desc: ""
})

const onSubmit = () => {
  console.log("submit!")
}
</script>

Hide Source

TIP

W3C regulates that

When there is only one single-line text input field in a form, the user agent should accept Enter in that field as a request to submit the form.

To prevent this behavior, you can add @submit.prevent on <bk-form>.

Multi-Column Form

When the vertical space is limited and the form is relatively simple, you can put it in one line.

Set the col-num attribute to specify the number of columns for the form layout.

Approved by

Activity zone

Activity zone

Activity time

<template>
  <bk-form :model="formData" :items="items" :col-num="3" class="demo-form-multi">
    <el-form-item>
      <el-button type="primary" @click="onSubmit">Query</el-button>
    </el-form-item>
  </bk-form>
</template>

<script lang="ts" setup>
import { reactive } from "vue"
import type { FormItemCtx } from "vue-business-kit"

const formData = reactive({
  user: "",
  region: "",
  date: ""
})

const items: FormItemCtx[] = [
  {
    label: "Approved by",
    type: "input",
    prop: "user",
    componentProps: {
      placeholder: "Approved by",
      clearable: true
    }
  },
  {
    label: "Activity zone",
    type: "select",
    prop: "region",
    componentProps: {
      placeholder: "Activity zone",
      clearable: true
    },
    children: [
      {
        label: "Zone one",
        value: "shanghai"
      },
      {
        label: "Zone two",
        value: "beijing"
      }
    ]
  },
  {
    label: "Activity time",
    type: "date-picker",
    prop: "date",
    componentProps: {
      placeholder: "Pick a date",
      clearable: true
    }
  }
]

const onSubmit = () => {
  console.log("submit!")
}
</script>

<style>
.demo-form-multi .el-input {
  --el-input-width: 220px;
}

.demo-form-multi .el-select {
  --el-select-width: 220px;
}
</style>

Hide Source

Alignment

Depending on your design, there are several different ways to align your label element.

You can set the label-position separately in items. If the value is empty, the label-position of bk-form is used.

The label-position attribute decides how labels align, it can be top or left. When set to top, labels will be placed at the top of the form field.

Form Align

LeftRightTop

Form Item Align

EmptyLeftRightTop

Name

Activity zone

Activity form

<template>
  <bk-form
    :label-position="formLabelAlign.labelPosition"
    label-width="auto"
    :model="formLabelAlign"
    :items="items"
    style="max-width: 600px"
  >
  </bk-form>
</template>

<script lang="ts" setup>
import { computed, reactive } from "vue"

import type { FormItemCtx } from "vue-business-kit"

const formLabelAlign = reactive({
  labelPosition: "right",
  itemLabelPosition: "",
  name: "",
  region: "",
  type: ""
})

const items = computed(() => {
  return [
    {
      label: "Form Align",
      type: "radio-group",
      prop: "labelPosition",
      labelPosition: "right",
      componentProps: {
        ariaLabel: "label position",
        type: "button"
      },
      children: [
        { label: "Left", value: "left" },
        { label: "Right", value: "right" },
        { label: "Top", value: "top" }
      ]
    },
    {
      label: "Form Item Align",
      type: "radio-group",
      prop: "itemLabelPosition",
      componentProps: {
        ariaLabel: "item label position",
        type: "button"
      },
      children: [
        { label: "Empty", value: "" },
        { label: "Left", value: "left" },
        { label: "Right", value: "right" },
        { label: "Top", value: "top" }
      ]
    },
    {
      label: "Name",
      type: "input",
      prop: "name",
      labelPosition: formLabelAlign.itemLabelPosition
    },
    {
      label: "Activity zone",
      type: "input",
      prop: "region",
      labelPosition: formLabelAlign.itemLabelPosition
    },
    {
      label: "Activity form",
      type: "input",
      prop: "type"
    }
  ] as FormItemCtx[]
})
</script>

Hide Source

Validation

Form component allows you to verify your data, helping you find and correct errors.

Just add the rules attribute to the Form component and provide validation rules. Each form item should define a prop field in the items configuration(Or the bk-form-item component) to bind validation to the corresponding model field. See more information at async-validator.

Activity name

Activity zone

Activity zone

Activity time

-

Instant delivery

Activity type

Online activitiesPromotion activitiesOffline activitiesSimple brand exposure

Resources

SponsorVenue

Activity form

<template>
  <bk-form
    ref="ruleFormRef"
    style="max-width: 600px"
    :model="ruleForm"
    :items="items"
    :rules="rules"
    label-width="auto"
  >
    <bk-form-item>
      <bk-button type="primary" @click="submitForm(ruleFormRef)"> Create </bk-button>
      <bk-button @click="resetForm(ruleFormRef)">Reset</bk-button>
    </bk-form-item>
  </bk-form>
</template>

<script lang="ts" setup>
import { reactive, ref } from "vue"

import type { FormInstance, FormItemCtx, FormRules } from "vue-business-kit"

interface RuleForm {
  name: string
  region: string
  count: string
  date1: string
  date2: string
  delivery: boolean
  location: string
  type: string[]
  resource: string
  desc: string
}

const items: FormItemCtx[] = [
  {
    label: "Activity name",
    type: "input",
    prop: "name"
  },
  {
    label: "Activity zone",
    type: "select",
    prop: "region",
    componentProps: {
      placeholder: "Activity zone"
    },
    children: [
      { label: "Zone one", value: "shanghai" },
      { label: "Zone two", value: "beijing" }
    ]
  },
  {
    label: "Activity time",
    type: "date-picker",
    prop: "date1",
    componentProps: {
      type: "datetimerange",
      placeholder: "Pick a date",
      style: { width: "100%" }
    }
  },
  {
    label: "Instant delivery",
    type: "switch",
    prop: "delivery"
  },
  {
    label: "Activity type",
    type: "checkbox-group",
    prop: "type",
    children: [
      { label: "Online activities", value: "Online activities" },
      { label: "Promotion activities", value: "Promotion activities" },
      { label: "Offline activities", value: "Offline activities" },
      { label: "Simple brand exposure", value: "Simple brand exposure" }
    ]
  },
  {
    label: "Resources",
    type: "radio-group",
    prop: "resource",
    children: [
      { label: "Sponsor", value: "Sponsor" },
      { label: "Venue", value: "Venue" }
    ]
  },
  {
    label: "Activity form",
    type: "input",
    prop: "desc",
    componentProps: {
      type: "textarea"
    }
  }
]

const ruleFormRef = ref<FormInstance>()
const ruleForm = reactive<RuleForm>({
  name: "Hello",
  region: "",
  count: "",
  date1: "",
  date2: "",
  delivery: false,
  location: "",
  type: [],
  resource: "",
  desc: ""
})

const rules = reactive<FormRules<RuleForm>>({
  name: [
    { required: true, message: "Please input Activity name", trigger: "blur" },
    { min: 3, max: 5, message: "Length should be 3 to 5", trigger: "blur" }
  ],
  region: [
    {
      required: true,
      message: "Please select Activity zone",
      trigger: "change"
    }
  ],
  count: [
    {
      required: true,
      message: "Please select Activity count",
      trigger: "change"
    }
  ],
  date1: [
    {
      type: "date",
      required: true,
      message: "Please pick a date",
      trigger: "change"
    }
  ],
  date2: [
    {
      type: "date",
      required: true,
      message: "Please pick a time",
      trigger: "change"
    }
  ],
  location: [
    {
      required: true,
      message: "Please select a location",
      trigger: "change"
    }
  ],
  type: [
    {
      type: "array",
      required: true,
      message: "Please select at least one activity type",
      trigger: "change"
    }
  ],
  resource: [
    {
      required: true,
      message: "Please select activity resource",
      trigger: "change"
    }
  ],
  desc: [{ required: true, message: "Please input activity form", trigger: "blur" }]
})

const submitForm = async (formEl: FormInstance | undefined) => {
  if (!formEl) return
  await formEl.epForm?.validate((valid, fields) => {
    if (valid) {
      console.log("submit!")
    } else {
      console.log("error submit!", fields)
    }
  })
}

const resetForm = (formEl: FormInstance | undefined) => {
  if (!formEl) return
  formEl.epForm?.resetFields()
}
</script>

Hide Source

Custom Validation Rules

This example shows how to customize your own validation rules to finish a two-factor password verification.

Here we use status-icon to reflect validation result as an icon.

Password

Confirm

Age

<template>
  <bk-form
    ref="ruleFormRef"
    style="max-width: 600px"
    :model="ruleForm"
    :items="items"
    :rules="rules"
    label-width="auto"
    status-icon
    class="demo-ruleForm"
  >
    <bk-form-item>
      <bk-button type="primary" @click="submitForm(ruleFormRef)"> Create </bk-button>
      <bk-button @click="resetForm(ruleFormRef)">Reset</bk-button>
    </bk-form-item>
  </bk-form>
</template>

<script lang="ts" setup>
import { reactive, ref } from "vue"

import type { FormInstance, FormRules, FormItemCtx } from "vue-business-kit"

const items: FormItemCtx[] = [
  {
    label: "Password",
    type: "input",
    componentProps: {
      type: "password",
      autocomplete: "off"
    },
    prop: "pass"
  },
  {
    label: "Confirm",
    type: "input",
    prop: "checkPass",
    componentProps: {
      type: "password",
      autocomplete: "off"
    }
  },
  {
    label: "Age",
    type: "input",
    prop: "age"
  }
]

const ruleFormRef = ref<FormInstance>()

const checkAge = (rule: any, value: any, callback: any) => {
  if (!value) {
    return callback(new Error("Please input the age"))
  }
  setTimeout(() => {
    if (!Number.isInteger(value)) {
      callback(new Error("Please input digits"))
    } else {
      if (value < 18) {
        callback(new Error("Age must be greater than 18"))
      } else {
        callback()
      }
    }
  }, 1000)
}

const validatePass = (rule: any, value: any, callback: any) => {
  if (value === "") {
    callback(new Error("Please input the password"))
  } else {
    if (ruleForm.checkPass !== "") {
      if (!ruleFormRef.value) return
      ruleFormRef.value.epForm?.validateField("checkPass")
    }
    callback()
  }
}
const validatePass2 = (rule: any, value: any, callback: any) => {
  if (value === "") {
    callback(new Error("Please input the password again"))
  } else if (value !== ruleForm.pass) {
    callback(new Error("Two inputs don't match!"))
  } else {
    callback()
  }
}

const ruleForm = reactive({
  pass: "",
  checkPass: "",
  age: ""
})

const rules = reactive<FormRules<typeof ruleForm>>({
  pass: [{ validator: validatePass, trigger: "blur" }],
  checkPass: [{ validator: validatePass2, trigger: "blur" }],
  age: [{ validator: checkAge, trigger: "blur" }]
})

const submitForm = (formEl: FormInstance | undefined) => {
  if (!formEl) return
  formEl.epForm?.validate((valid) => {
    if (valid) {
      console.log("submit!")
    } else {
      console.log("error submit!")
    }
  })
}

const resetForm = (formEl: FormInstance | undefined) => {
  if (!formEl) return
  formEl.epForm?.resetFields()
}
</script>

Hide Source

TIP

Custom validate callback function must be called. See more advanced usage at async-validator.

Add/Delete Form Item

In addition to passing all validation rules at once on the form component, you can also pass the validation rules or delete rules on a single form field dynamically.

Email

Domain0

<template>
  <bk-form
    ref="formRef"
    :model="dynamicValidateForm"
    :items="items"
    label-width="auto"
    style="max-width: 600px"
    class="demo-dynamic"
  >
    <bk-form-item
      v-for="(domain, index) in dynamicValidateForm.domains"
      :key="domain.key"
      :label="'Domain' + index"
      :prop="'domains.' + index + '.value'"
      :rules="{
        required: true,
        message: 'domain can not be null',
        trigger: 'blur'
      }"
    >
      <el-input v-model="domain.value" />
      <bk-button class="mt-2" @click.prevent="removeDomain(domain)"> Delete </bk-button>
    </bk-form-item>
    <bk-form-item>
      <bk-button type="primary" @click="submitForm(formRef)">Submit</bk-button>
      <bk-button @click="addDomain">New domain</bk-button>
      <bk-button @click="resetForm(formRef)">Reset</bk-button>
    </bk-form-item>
  </bk-form>
</template>

<script lang="ts" setup>
import { reactive, ref } from "vue"

import type { FormInstance, FormItemCtx } from "vue-business-kit"

const items: FormItemCtx[] = [
  {
    label: "Email",
    type: "input",
    prop: "email",
    rules: [
      {
        required: true,
        message: "Please input email address",
        trigger: "blur"
      },
      {
        type: "email",
        message: "Please input correct email address",
        trigger: ["blur", "change"]
      }
    ]
  }
]

const formRef = ref<FormInstance>()
const dynamicValidateForm = reactive<{
  domains: DomainItem[]
  email: string
}>({
  domains: [
    {
      key: 1,
      value: ""
    }
  ],
  email: ""
})

interface DomainItem {
  key: number
  value: string
}

const removeDomain = (item: DomainItem) => {
  const index = dynamicValidateForm.domains.indexOf(item)
  if (index !== -1) {
    dynamicValidateForm.domains.splice(index, 1)
  }
}

const addDomain = () => {
  dynamicValidateForm.domains.push({
    key: Date.now(),
    value: ""
  })
}

const submitForm = (formEl: FormInstance | undefined) => {
  if (!formEl) return
  formEl.epForm?.validate((valid) => {
    if (valid) {
      console.log("submit!")
    } else {
      console.log("error submit!")
    }
  })
}

const resetForm = (formEl: FormInstance | undefined) => {
  if (!formEl) return
  formEl.epForm?.resetFields()
}
</script>

Hide Source

Number Validate

Number Validate need a .number modifier added on the input v-model binding，it's used to transform the string value to the number which is provided by Vue.

age

<template>
  <bk-form
    ref="formRef"
    style="max-width: 600px"
    :model="numberValidateForm"
    label-width="auto"
    class="demo-ruleForm"
  >
    <bk-form-item
      label="age"
      prop="age"
      :rules="[
        { required: true, message: 'age is required' },
        { type: 'number', message: 'age must be a number' }
      ]"
    >
      <el-input v-model.number="numberValidateForm.age" type="text" autocomplete="off" />
    </bk-form-item>
    <bk-form-item>
      <bk-button type="primary" @click="submitForm(formRef)">Submit</bk-button>
      <bk-button @click="resetForm(formRef)">Reset</bk-button>
    </bk-form-item>
  </bk-form>
</template>

<script lang="ts" setup>
import { reactive, ref } from "vue"

import type { FormInstance } from "vue-business-kit"

const formRef = ref<FormInstance>()

const numberValidateForm = reactive({
  age: ""
})

const submitForm = (formEl: FormInstance | undefined) => {
  if (!formEl) return
  formEl.epForm?.validate((valid) => {
    if (valid) {
      console.log("submit!")
    } else {
      console.log("error submit!")
    }
  })
}

const resetForm = (formEl: FormInstance | undefined) => {
  if (!formEl) return
  formEl.epForm?.resetFields()
}
</script>

Hide Source

TIP

When an bk-form-item is nested in another bk-form-item, its label width will be 0. You can set label-width on that bk-form-item if needed.

Size Control

All components in a Form inherit their size attribute from that Form. Similarly, FormItem also has a size attribute.

Still you can fine tune each component's size if you don't want that component to inherit its size from From or FormItem.

largedefaultsmall

LeftRightTop

Activity name

Activity zone

please select your zone

Activity time

-

Instant delivery

Activity type

Online activitiesPromotion activitiesOffline activitiesSimple brand exposure

Resources

SponsorVenue

<template>
  <div>
    <el-radio-group v-model="size" aria-label="size control">
      <el-radio-button value="large">large</el-radio-button>
      <el-radio-button value="default">default</el-radio-button>
      <el-radio-button value="small">small</el-radio-button>
    </el-radio-group>
    <el-radio-group v-model="labelPosition" aria-label="position control">
      <el-radio-button value="left">Left</el-radio-button>
      <el-radio-button value="right">Right</el-radio-button>
      <el-radio-button value="top">Top</el-radio-button>
    </el-radio-group>
  </div>
  <br />
  <bk-form
    style="max-width: 600px"
    :model="sizeForm"
    :items="items"
    label-width="auto"
    :label-position="labelPosition"
    :size="size"
  >
    <bk-form-item>
      <bk-button type="primary" @click="onSubmit">Create</bk-button>
      <bk-button>Cancel</bk-button>
    </bk-form-item>
  </bk-form>
</template>

<script lang="ts" setup>
import { reactive, ref } from "vue"

import type { ComponentSize, FormItemCtx, FormProps } from "vue-business-kit"

const items: FormItemCtx[] = [
  {
    label: "Activity name",
    type: "input",
    prop: "name"
  },
  {
    label: "Activity zone",
    type: "select",
    prop: "region",
    componentProps: {
      placeholder: "please select your zone"
    },
    children: [
      { label: "Zone one", value: "shanghai" },
      { label: "Zone two", value: "beijing" }
    ]
  },
  {
    label: "Activity time",
    type: "date-picker",
    prop: "date1",
    componentProps: {
      type: "datetimerange",
      placeholder: "Pick a date",
      style: { width: "100%" }
    }
  },
  {
    label: "Instant delivery",
    type: "switch",
    prop: "delivery"
  },
  {
    label: "Activity type",
    type: "checkbox-group",
    prop: "type",
    children: [
      { label: "Online activities", value: "Online activities" },
      { label: "Promotion activities", value: "Promotion activities" },
      { label: "Offline activities", value: "Offline activities" },
      { label: "Simple brand exposure", value: "Simple brand exposure" }
    ]
  },
  {
    label: "Resources",
    type: "radio-group",
    prop: "resource",
    children: [
      { label: "Sponsor", value: "Sponsor" },
      { label: "Venue", value: "Venue" }
    ]
  }
]

const size = ref<ComponentSize>("default")
const labelPosition = ref<FormProps["labelPosition"]>("right")

const sizeForm = reactive({
  name: "",
  region: "",
  date1: "",
  date2: "",
  delivery: false,
  type: [],
  resource: "",
  desc: ""
})

function onSubmit() {
  console.log("submit!")
}
</script>

<style>
.el-radio-group {
  margin-right: 12px;
}
</style>

Hide Source

Accessibility

When only a single input (or related control such as select or checkbox) is inside of a bk-form-item, the form item's label will automatically be attached to that input. However, if multiple inputs are inside of the bk-form-item, the form item will be assigned the WAI-ARIA role of group instead. In this case, it is your responsibility to assign assistive labels to the individual inputs.

"Full Name" label is automatically attached to the input:

Full Name

"Your Information" serves as a label for the group of inputs.
You must specify labels on the individal inputs. Placeholders are not replacements for using the "label" attribute.

Your Information

<template>
  <bk-form label-position="left" label-width="auto" style="max-width: 600px">
    <el-space fill>
      <el-alert type="info" show-icon :closable="false">
        <p>"Full Name" label is automatically attached to the input:</p>
      </el-alert>
      <bk-form-item label="Full Name">
        <el-input v-model="formAccessibility.fullName" />
      </bk-form-item>
    </el-space>
    <el-space fill>
      <el-alert type="info" show-icon :closable="false">
        <p>
          "Your Information" serves as a label for the group of inputs. <br />
          You must specify labels on the individal inputs. Placeholders are not replacements for
          using the "label" attribute.
        </p>
      </el-alert>
      <bk-form-item label="Your Information">
        <el-row :gutter="20">
          <el-col :span="12">
            <el-input
              v-model="formAccessibility.firstName"
              aria-label="First Name"
              placeholder="First Name"
            />
          </el-col>
          <el-col :span="12">
            <el-input
              v-model="formAccessibility.lastName"
              aria-label="Last Name"
              placeholder="Last Name"
            />
          </el-col>
        </el-row>
      </bk-form-item>
    </el-space>
  </bk-form>
</template>

<script lang="ts" setup>
import { reactive } from "vue"

const formAccessibility = reactive({
  fullName: "",
  firstName: "",
  lastName: ""
})
</script>

Hide Source

Form API

Form Attributes

Name	Description	Type	Default
items	Configuration array for form items, each item can specify type, componentProps, and children	array	—
colNum	Number of columns for multi-column form layout	number	1

Element Plus Form Attributes

Name	Description	Type	Default
model	Data of form component.	object	—
rules	Validation rules of form.	object	—
inline	Whether the form is inline. (It is recommended to use the col-num attribute)	boolean	false
label-position	Position of label. If set to 'left' or 'right', label-width prop is also required.	enum	right
label-width	Width of label, e.g. '50px'. All its direct child form items will inherit this value. auto is supported.	string / number	''
label-suffix	Suffix of the label.	string	''
hide-required-asterisk	Whether to hide required fields should have a red asterisk (star) beside their labels.	boolean	false
require-asterisk-position	Position of asterisk.	enum	left
show-message	Whether to show the error message.	boolean	true
inline-message	Whether to display the error message inline with the form item.	boolean	false
status-icon	Whether to display an icon indicating the validation result.	boolean	false
validate-on-rule-change	Whether to trigger validation when the rules prop is changed.	boolean	true
size	Control the size of components in this form.	enum	—
disabled	Whether to disable all components in this form. If set to true, it will override the disabled prop of the inner component.	boolean	false
scroll-to-error	When validation fails, scroll to the first error form entry.	boolean	false
scroll-into-view-options	When validation fails, it scrolls to the first error item based on the scrollIntoView option. scrollIntoView.	object / boolean	true

Form Events

Element Plus Form Events

Name	Description	Type
validate	triggers after a form item is validated	Function

Form Slots

Element Plus Form Slots

Name	Description	Subtags
default	customize default content	FormItem

Form Exposes

Element Plus Form Exposes

Name	Description	Type
validate	Validate the whole form. Receives a callback or returns Promise.	Function
validateField	Validate specified fields.	Function
resetFields	Reset specified fields and remove validation result.	Function
scrollToField	Scroll to the specified fields.	Function
clearValidate	Clear validation messages for all or specified fields.	Function
fields	Get all fields context.	array
getField	Get a field context.	Function

FormItem API

FormItem Attributes

Name	Description	Type	Default
type required	Type of the form item component (e.g., 'input', 'select', 'radio')	string	—
componentProps	Additional props to pass to the underlying component	object	—
children	Nested form items for complex layouts	array	—

Element Plus FormItem Attributes

Name	Description	Type	Default
prop	A key of model. It could be a path of the property (e.g a.b.0 or ['a', 'b', '0']). In the use of validate and resetFields method, the attribute is required.	string / string[]	—
label	Label text.	string	—
label-position	Position of item label. If set to 'left' or 'right', label-width prop is also required. Default extend label-position of form.	enum	''
label-width	Width of label, e.g. '50px'. 'auto' is supported.	string / number	—
required	Whether the field is required or not, will be determined by validation rules if omitted.	boolean	—
rules	Validation rules of form, see the following table, more advanced usage at async-validator.	object	—
error	Field error message, set its value and the field will validate error and show this message immediately.	string	—
show-message	Whether to show the error message.	boolean	true
inline-message	Inline style validate message.	boolean	false
size	Control the size of components in this form-item.	enum	—
for	Same as for in native label.	string	—
validate-status	Validation state of formItem.	enum	—

FormItemRule

Element Plus FormItemRule

Name	Description	Type	Default
trigger	How the validator is triggered.	enum	—

TIP

If you don't want to trigger the validator based on input events, set the validate-event attribute as false on the corresponding input type components (<el-input>, <el-radio>, <el-select>, ...).

FormItem Slots

Element Plus FormItem Slots

Name	Description	Type
default	Content of Form Item.	—
label	Custom content to display on label.	object
error	Custom content to display validation message.	object

FormItem Exposes

Element Plus FormItem Exposes

Name	Description	Type
size	Form item size.	object
validateMessage	Validation message.	object
validateState	Validation state.	object
validate	Validate form item.	Function
resetField	Reset current field and remove validation result.	Function
clearValidate	Remove validation status of the field.	Function