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
| Attribute | Description | Type | Accepted Values | Default |
|---|---|---|---|---|
| model | data of form component | object | — | — |
| rules | validation rules of form | object | — | — |
| inline | whether the form is inline | boolean | — | false |
| label-position | position of label. If set to 'left' or 'right', label-width prop is also required | string | left / right / top | right |
| label-width | width of label, e.g. '50px'. All its direct child form items will inherit this value. Width auto is supported. | string / number | — | — |
| label-suffix | suffix of the label | string | — | — |
| hide-required-asterisk | whether required fields should have a red asterisk (star) beside their labels | boolean | — | false |
| 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 | string | large / default / small | — |
| disabled | whether to disabled all components in this form. If set to true, it cannot be overridden by its inner components' disabled prop | boolean | — | false |
Form Methods
| Method | Description | Parameters |
|---|---|---|
| validate | validate 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 omitted | Function(callback: Function(boolean, object)) |
| validateField | validate one or several form items | Function(props: string | array, callback: Function(errorMessage: string)) |
| resetFields | reset all the fields and remove validation result | — |
| scrollToField | Scroll to the specified form field | Function(prop: string) |
| clearValidate | clear 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 cleared | Function(props: string | array) |
Form Events
| Event Name | Description | Parameters |
|---|---|---|
| validate | triggers after a form item is validated | prop name of the form item being validated, whether validation is passed and the error message if not |
Form Slots
| Name | Description | Subtags |
|---|---|---|
| — | customize of Dropdown Item | Form-Item |
Form-Item Attributes
| Attribute | Description | Type | Accepted Values | Default |
|---|---|---|---|---|
| prop | a key of model. In the use of validate and resetFields method, the attribute is required | string | keys of model that passed to form | |
| label | label | string | — | — |
| label-width | width of label, e.g. '50px'. Width auto is supported. | string / number | — | — |
| required | whether the field is required or not, will be determined by validation rules if omitted | boolean | — | false |
| rules | validation rules of form, see the following table, more advanced usage at async-validator | object / array | — | — |
| 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 | string | large / default / small | default |
Rules
| Attribute | Description | Type | Accepted Values | Default |
|---|---|---|---|---|
| trigger | how the validator is triggered | string | blur / change | — |
Form-Item Slots
| Name | Description |
|---|---|
| — | content of Form Item |
| label | Custom content to display on label. The scope parameter is |
| error | Custom content to display validation message. The scope parameter is |
Form-Item Methods
| Method | Description | Parameters |
|---|---|---|
| resetField | reset current field and remove validation result | — |
| clearValidate | remove validation status of the field | — |