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

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 message for specified fields.	`Function`

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-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
) => 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>
    >
  >

Source

Component • Docs

Contributors

DateTime Picker

Input

Form #

Basic Form #

Inline Form #

Alignment #

Validation #

Custom Validation Rules #

Add/Delete Form Item #

Number Validate #

Size Control #

Accessibility #

Form API #

Form Attributes #

Form Events #

Form Slots #

Form Exposes #

FormItem API #

FormItem Attributes #

FormItemRule #

FormItem Slots #

FormItem Exposes #

Type Declarations #

Source #

Contributors #