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.

Add/Delete Form Item

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.

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.

Form API

Form Attributes

AttributeDescriptionTypeDefault
modelData of form component.Record<string, any>
rulesValidation rules of form.FormRules
inlineWhether the form is inline.booleanfalse
label-positionPosition of label. If set to 'left' or 'right', label-width prop is also required.'left' | 'right' | 'top''right'
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 required fields should have a red asterisk (star) beside their labels.booleanfalse
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.'large' | 'default' | 'small'
disabledWhether to disable all components in this form. If set to true, it will override the disabled prop of the inner component.booleanfalse

Form Methods

MethodDescriptionType
validateValidate the whole form. Receives a callback or returns Promise.(callback?: (isValid: boolean, invalidFields?: ValidateFieldsError) => void) => Promise<void>
validateFieldValidate specified fields.(props?: Arrayable<FormItemProp>, callback?: (isValid: boolean, invalidFields?: ValidateFieldsError) => void) => Promise<void>
resetFieldsReset specified fields and remove validation result.(props?: Arrayable<FormItemProp>) => void
scrollToFieldScroll to the specified fields.(prop: FormItemProp) => void
clearValidateClear validation message for specified fields.(props?: Arrayable<FormItemProp>) => void

Form Events

Event NameDescriptionParameters
validatetriggers after a form item is validated(prop: FormItemProp, isValid: boolean, message: string) => void

Form Slots

NameDescriptionSubtags
-customize default contentFormItem

Form Item API

Form Item Attributes

AttributeDescriptionTypeDefault
propA key of model. It could be an array of property paths (e.g ['a', 'b', 0]). In the use of validate and resetFields method, the attribute is required.string | string[]
labelLabel text.string
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.booleanfalse
rulesValidation rules of form, see the following table, more advanced usage at async-validator.FormItemRule | FormItemRule[]
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.booleanfalse
sizeControl the size of components in this form-item.'large' | 'default' | 'small''default'

FormItemRule

NameDescriptionTypeDefault
triggerHow the validator is triggered.'blur' | 'change'

Form Item Slots

NameDescriptionSlot Scope
Content of Form Item.
labelCustom content to display on label.{ label }
errorCustom content to display validation message.{ error }

Form Item Methods

MethodDescriptionType
resetFieldReset current field and remove validation result.() => void
clearValidateRemove validation status of the field.() => void

Source

ComponentDocs

Contributors