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.

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.

Alignment

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

Validation

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

Custom validation rules

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

TIP

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

Delete or add form items dynamically

Number Validate

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.

Form Attributes

AttributeDescriptionTypeAccepted ValuesDefault
modeldata of form componentobject
rulesvalidation rules of formobject
inlinewhether the form is inlinebooleanfalse
label-positionposition of label. If set to 'left' or 'right', label-width prop is also requiredstringleft / right / topright
label-widthwidth of label, e.g. '50px'. All its direct child form items will inherit this value. Width auto is supported.string / number
label-suffixsuffix of the labelstring
hide-required-asteriskwhether required fields should have a red asterisk (star) beside their labelsbooleanfalse
show-messagewhether to show the error messagebooleantrue
inline-messagewhether to display the error message inline with the form itembooleanfalse
status-iconwhether to display an icon indicating the validation resultbooleanfalse
validate-on-rule-changewhether to trigger validation when the rules prop is changedbooleantrue
sizecontrol the size of components in this formstringmedium / small / mini
disabledwhether to disabled all components in this form. If set to true, it cannot be overridden by its inner components' disabled propbooleanfalse

Form Methods

MethodDescriptionParameters
validatevalidate the whole form. Takes a callback as a param. After validation, the callback will be executed with two params: a boolean indicating if the validation has passed, and an object containing all fields that fail the validation. Returns a promise if callback is omittedFunction(callback: Function(boolean, object))
validateFieldvalidate one or several form itemsFunction(props: string | array, callback: Function(errorMessage: string))
resetFieldsreset all the fields and remove validation result
scrollToFieldScroll to the specified form fieldFunction(prop: string)
clearValidateclear validation message for certain fields. The parameter is prop name or an array of prop names of the form items whose validation messages will be removed. When omitted, all fields' validation messages will be clearedFunction(props: string | array)

Form Events

Event NameDescriptionParameters
validatetriggers after a form item is validatedprop name of the form item being validated, whether validation is passed and the error message if not

Form Slots

NameDescriptionSubtags
customize of Dropdown ItemForm-Item

Form-Item Attributes

AttributeDescriptionTypeAccepted ValuesDefault
propa key of model. In the use of validate and resetFields method, the attribute is requiredstringkeys of model that passed to form
labellabelstring
label-widthwidth of label, e.g. '50px'. Width auto is supported.string / number
requiredwhether the field is required or not, will be determined by validation rules if omittedbooleanfalse
rulesvalidation rules of form, see the following table, more advanced usage at async-validatorobject / array
errorfield error message, set its value and the field will validate error and show this message immediatelystring
show-messagewhether to show the error messagebooleantrue
inline-messageinline style validate messagebooleanfalse
sizecontrol the size of components in this form-itemstringmedium / small / mini

Rules

AttributeDescriptionTypeAccepted ValuesDefault
triggerhow the validator is triggeredstringblur / change

Form-Item Slots

NameDescription
content of Form Item
labelCustom content to display on label. The scope parameter is { label }
errorCustom content to display validation message. The scope parameter is { error }

Form-Item Methods

MethodDescriptionParameters
resetFieldreset current field and remove validation result
clearValidateremove validation status of the field