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.
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.
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.
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.
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.
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.
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
Name | Description | Type | 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. |
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 2.3.2 | When validation fails, it scrolls to the first error item based on the scrollIntoView option. scrollIntoView. | object / boolean
|
— |
Form Events
Name | Description | Type |
---|---|---|
validate | triggers after a form item is validated | Function |
Form Slots
Name | Description | Subtags |
---|---|---|
default | customize default content | FormItem |
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 2.7.3 | Get all fields context. | array |
FormItem API
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 2.7.7 | Position of item label. If set to 'left' or
'right' , label-width prop is also required. Default extend
label-postion 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. | string / boolean
|
'' |
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
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
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
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 |
Type Declarations
Show declarations
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
}