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 Form ​

It includes all kinds of input items, such as input, select, radio and checkbox.

In each form component, you need a form-item field to be the container of your input item.

Activity name
Activity zone
please select your zone
Activity time
-
Instant delivery
Activity type
Resources
Activity form

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 <el-form>.

Inline Form ​

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

Set the inline attribute to true and the form will be inline.

Approved by
Activity zone
Activity zone
Activity time

Alignment ​

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

You can set label-position of el-form-item separately 2.7.7. If the value is empty, the label-position of el-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
Form Item Align
Name
Activity zone
Activity form

Validation ​

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

Just add the rules attribute for Form component, pass validation rules, and set prop attribute for FormItem as a specific key that needs to be validated. See more information at async-validator.

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.

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

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

TIP

When an el-form-item is nested in another el-form-item, its label width will be 0. You can set label-width on that el-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.


Activity name
Activity zone
please select your zone
Activity time
-
Activity type
Resources

Accessibility ​

When only a single input (or related control such as select or checkbox) is inside of a el-form-item, the form item's label will automatically be attached to that input. However, if multiple inputs are inside of the el-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
Your Information

Form API ​

Form Attributes ​

NameDescriptionTypeDefault
modelData of form component.object—
rulesValidation rules of form.object—
inlineWhether the form is inline.booleanfalse
label-positionPosition of label. If set to 'left' or 'right', label-width prop is also required.enumright
label-widthWidth of label, e.g. '50px'. All its direct child form items will inherit this value. auto is supported.string / number''
label-suffixSuffix of the label.string''
hide-required-asteriskWhether to hide required fields should have a red asterisk (star) beside their labels.booleanfalse
require-asterisk-positionPosition of asterisk.enumleft
show-messageWhether to show the error message.booleantrue
inline-messageWhether to display the error message inline with the form item.booleanfalse
status-iconWhether to display an icon indicating the validation result.booleanfalse
validate-on-rule-changeWhether to trigger validation when the rules prop is changed.booleantrue
sizeControl the size of components in this form.enum—
disabledWhether to disable all components in this form. If set to true, it will override the disabled prop of the inner component.booleanfalse
scroll-to-errorWhen validation fails, scroll to the first error form entry.booleanfalse
scroll-into-view-options 2.3.2When validation fails, it scrolls to the first error item based on the scrollIntoView option. scrollIntoView.object / boolean—

Form Events ​

NameDescriptionType
validatetriggers after a form item is validatedFunction

Form Slots ​

NameDescriptionSubtags
defaultcustomize default contentFormItem

Form Exposes ​

NameDescriptionType
validateValidate the whole form. Receives a callback or returns Promise.Function
validateFieldValidate specified fields.Function
resetFieldsReset specified fields and remove validation result.Function
scrollToFieldScroll to the specified fields.Function
clearValidateClear validation messages for all or specified fields.Function
fields 2.7.3Get all fields context.array

FormItem API ​

FormItem Attributes ​

NameDescriptionTypeDefault
propA 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[]—
labelLabel text.string—
label-position 2.7.7Position of item label. If set to 'left' or 'right', label-width prop is also required. Default extend label-postion of form.enum''
label-widthWidth of label, e.g. '50px'. 'auto' is supported.string / number''
requiredWhether the field is required or not, will be determined by validation rules if omitted.boolean—
rulesValidation rules of form, see the following table, more advanced usage at async-validator.object—
errorField error message, set its value and the field will validate error and show this message immediately.string—
show-messageWhether to show the error message.booleantrue
inline-messageInline style validate message.string / boolean''
sizeControl the size of components in this form-item.enum—
forSame as for in native label.string—
validate-statusValidation state of formItem.enum—

FormItemRule ​

NameDescriptionTypeDefault
triggerHow 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 ​

NameDescriptionType
defaultContent of Form Item.—
labelCustom content to display on label.object
errorCustom content to display validation message.object

FormItem Exposes ​

NameDescriptionType
sizeForm item size.object
validateMessageValidation message.object
validateStateValidation state.object
validateValidate form item.Function
resetFieldReset current field and remove validation result.Function
clearValidateRemove validation status of the field.Function

Type Declarations ​

Show declarations
ts
type Arrayable<T> = T | T[]

type FormValidationResult = Promise<boolean>

// ValidateFieldsError: see [async-validator](https://github.com/yiminghe/async-validator/blob/master/src/interface.ts)
type FormValidateCallback = (
  isValid: boolean,
  invalidFields?: ValidateFieldsError
) => Promise<void> | void

// RuleItem: see [async-validator](https://github.com/yiminghe/async-validator/blob/master/src/interface.ts)
interface FormItemRule extends RuleItem {
  trigger?: Arrayable<string>
}

type Primitive = null | undefined | string | number | boolean | symbol | bigint
type BrowserNativeObject = Date | FileList | File | Blob | RegExp
type IsTuple<T extends ReadonlyArray<any>> = number extends T['length']
  ? false
  : true
type ArrayMethodKey = keyof any[]
type TupleKey<T extends ReadonlyArray<any>> = Exclude<keyof T, ArrayMethodKey>
type ArrayKey = number
type PathImpl<K extends string | number, V> = V extends
  | Primitive
  | BrowserNativeObject
  ? `${K}`
  : `${K}` | `${K}.${Path<V>}`
type Path<T> = T extends ReadonlyArray<infer V>
  ? IsTuple<T> extends true
    ? {
        [K in TupleKey<T>]-?: PathImpl<Exclude<K, symbol>, T[K]>
      }[TupleKey<T>]
    : PathImpl<ArrayKey, V>
  : {
      [K in keyof T]-?: PathImpl<Exclude<K, symbol>, T[K]>
    }[keyof T]
type FieldPath<T> = T extends object ? Path<T> : never
// MaybeRef: see [@vueuse/core](https://github.com/vueuse/vueuse/blob/main/packages/shared/utils/types.ts)
// UnwrapRef: see [vue](https://github.com/vuejs/core/blob/main/packages/reactivity/src/ref.ts)
type FormRules<T extends MaybeRef<Record<string, any> | string> = string> =
  Partial<
    Record<
      UnwrapRef<T> extends string ? UnwrapRef<T> : FieldPath<UnwrapRef<T>>,
      Arrayable<FormItemRule>
    >
  >

type FormItemValidateState = typeof formItemValidateStates[number]
type FormItemProps = ExtractPropTypes<typeof formItemProps>

type FormItemContext = FormItemProps & {
  $el: HTMLDivElement | undefined
  size: ComponentSize
  validateState: FormItemValidateState
  isGroup: boolean
  labelId: string
  inputIds: string[]
  hasLabel: boolean
  fieldValue: any
  addInputId: (id: string) => void
  removeInputId: (id: string) => void
  validate: (
    trigger: string,
    callback?: FormValidateCallback
  ) => FormValidationResult
  resetField(): void
  clearValidate(): void
}

Source ​

Component • Style • Docs

Contributors ​