🌏 Translated with the assistance of DeepSeek and ChatGPT

Form

Used to collect information.

Basic usage

Form uses model to pass the form data object and rules to pass validation rules; in FormItem, field sets the form item field for validation, reset, and other operations.

FormItem's rule takes precedence over Form's rules for the same field.

When manually triggering validation using the Form component's validate method, it ignores the trigger condition configured on rules or rule, validates all existing FormItems, and stops at the first failing rule.

Additionally, note that the field property of FormItem is not reactive.

*  Input

*  Radio

Yes

No

*  Checkbox

A

B

C

D

Number

*  Tags

*  Text

*  Switch

*  Select

Please select...

*  Nest

*  Email

*  URL

Slider

*  Number String

Hide source code

useForm returns an object for manipulating the form, which can be passed to the Form's form property.

Either the model or form property of Form must be provided.

*  Username

*  Email

Hide source code

Custom validation

Use validator to provide custom validation rules.

The Answer to the Great Question Of Life, the Universe and Everything...

Answer

Hide source code

Disabled & Readonly

Set the form's disabled state using disabled and the readonly state using readonly.

The disabled or readonly attribute of the Form component affects all button components within it (including Button and ButtonGroup) and the data input components within each FormItem, while the disabled or readonly attribute of an individual FormItem only affects the button and data input components within that specific FormItem.

These two properties follow an 'OR' logic throughout the component hierarchy: if any level—Form, FormItem, or the component itself—is set to disabled or readonly, the component will be rendered in that state.

Disabled

*  Username

*  Email

Readonly

*  Username

*  Email

Hide source code

Label alignment

Set label alignment with labelAlign.

Input

Input

Input

Hide source code

Child element width

Use labelProps and contentProps to modify the Col component props for the label and content areas.

When labelAutoWidth is set, the label area width becomes adaptive and the content area width will change accordingly.

Input

Input

Hide source code

Form size

The form is available in different sizes.

The size property of the Form component affects all button components within it (including Button and ButtonGroup) and the data input components within each FormItem.

For button components and data input components inside Form and FormItem, if the size property is not provided or is undefined, it will be set to match the Form's size property; if explicitly set, the provided value takes precedence.

Small

Medium

Large

Input

Number

Radio

Yes

No

Checkbox

A

B

C

D

Switch

Hide source code

API

useForm

function useForm<T extends Record<string | number, any> = Record<string | number, any>>(options?: {
    initialValues?: T;
}): UseFormReturn<T>

export interface UseFormReturn<
	T extends Record<string | number, any> = Record<string | number, any>
> {
	model: Ref<T>
	validate: (field?: string | string[]) => FormValidateResult
	reset: (field?: string | string[]) => void
	clearValidation: (field?: string | string[]) => void
	register: (registerOptions: UseFormRegisterOptions) => void
}

FormProps

Attribute	Type	Optional	Default	Description	Version
model	Record<number | string, any>	True		The form data object. Either form or model must be provided.	0.0.3
form	FormInstance	True		Form object returned by useForm, used to manipulate the form via a hook. Either form or model must be provided.	0.0.3
rules	Record<string, RuleItem | RuleItem[]>	True		Validation rules.	0.0.3
enterSubmit	boolean	True	false	Whether to allow Enter to submit the form.	0.2.0
disabled	boolean	True	false	Whether the form is disabled.	0.0.3
readonly	boolean	True	false	Whether the form is read-only.	0.0.3
size	'small' | 'medium' | 'large'	True	'medium'	Form size.	0.0.3
labelAlign	'left' | 'right' | 'top'	True	'right'	Label alignment.	0.0.3
showAsterisk	boolean	True		Whether to show an asterisk.	0.0.3
asteriskPlacement	'left' | 'right' | 'end'	True	'left'	Position of the asterisk.	0.0.3
labelAutoWidth	boolean	True	false	Enable auto width for form item labels.	0.0.3
rowProps	RowProps & RestAttrs	True		Props for the form item row container.	0.0.3
labelProps	ColProps & RestAttrs	True		Props for the form item's label column.	0.0.3
contentProps	ColProps & RestAttrs	True		Props for the form item's content column.	0.0.3
pollSizeChange	boolean	True	false	Enables polling for component size changes. This also affects the property of the same name in button and data input components within its subtree.	0.1.0

UseFormReturn

Attribute	Type	Optional	Default	Description	Version
model	Ref<Record<string | number, any>>	False		The form data object.	0.0.3
validate	(field?: string | string[]) => FormValidateResult	False		Manually triggers form validation. Validates all fields when no parameters are provided. Can only be called after the Form is mounted.	0.0.3
reset	(field?: string | string[]) => void	False		Manually triggers form reset. Resets all fields when no parameters are provided. Can only be called after the Form is mounted.	0.0.3
clearValidation	(field?: string | string[]) => void	False		Clears the form validation status. Clears validation for all fields when no parameters are provided. Can only be called after the Form is mounted.	0.0.3

FormEvents

Event	Parameter	Description	Version
submit	form: Record<number | string, any>, event: SubmitEvent	Callback for native form submit.	0.0.3
reset	form: Record<number | string, any>, event: Event	Callback for native form reset.	0.0.3

FormSlots

Slot	Parameter	Description	Version
default		Used to render form items.	0.0.3

FormExpose

Attribute	Type	Optional	Default	Description	Version
validate	(field?: string | string[]) => FormValidateResult	False		Manually trigger form validation; without arguments validates all fields.	0.0.3
reset	(field?: string | string[]) => void	False		Manually trigger form reset; without arguments resets all fields.	0.0.3
clearValidation	(field?: string | string[]) => void	False		Clear validation state; without arguments clears all fields.	0.0.3

RuleItem

Attribute	Type	Optional	Default	Description	Version
required	boolean	True	false	Whether the field is required.	0.0.3
message	string	True		Error message shown on validation failure; an empty string will not trigger an error.	0.0.3
trigger	RuleTrigger | RuleTrigger[]	True	['change', 'blur']	Event that triggers validation.	0.0.3
type	FieldType | FieldType[]	True		Field type validation.	0.0.3
max	number	True		Maximum value limit, only for numeric values.	0.0.3
min	number	True		Minimum value limit, only for numeric values.	0.0.3
maxLength	number	True		Maximum length limit, applicable when the value is a string or array.	0.0.3
minLength	number	True		Minimum length limit, applicable when the value is a string or array.	0.0.3
email	boolean	True	false	Whether the value must be an email address (applies when value is a string).	0.0.3
url	boolean	True	false	Whether the value must be a URL (applies when value is a string).	0.0.3
numberString	boolean	True	false	Whether the value must be a numeric string (applies when value is a string).	0.0.3
level	RuleLevel	True	'error'	Failure level; only 'error' will cause the form validation to fail.	0.0.3
validator	(value: any, model: Record<number | string, any>) => string | void | Promise<void | string>	True		Custom validation function that returns an error message string; a falsy/empty return indicates success.	0.0.3

FormItemProps

Attribute	Type	Optional	Default	Description	Version
field	string	True		The associated form field name. Supports field path syntax, e.g. 'user[0].info.name'. This property is not reactive.	0.0.3
label	string	True		Label text.	0.0.3
rule	RuleItem | RuleItem[]	True		Validation rules.	0.0.3
disabled	boolean	True		Whether to disable. The final disabled state is determined by OR operation with disabled from Form.	0.0.3
readonly	boolean	True		Whether to be read-only. The final read-only state is determined by OR operation with readonly from Form.	0.0.3
labelAlign	'left' | 'right' | 'top'	True		Label alignment for this item.	0.0.3
showAsterisk	boolean	True		Whether to show an asterisk.	0.0.3
asteriskPlacement	'left' | 'right' | 'end'	True		Position of the asterisk.	0.0.3
rowProps	RowProps & RestAttrs	True		Props for the form item's row container.	0.0.3
labelProps	ColProps & RestAttrs	True		Props for the form item's label column.	0.0.3
contentProps	ColProps & RestAttrs	True		Props for the form item's content column.	0.0.3
pollSizeChange	boolean	True	false	Enables polling for component size changes. This also affects the property of the same name in button and data input components within its subtree.	0.1.0

FormItemSlots

Slot	Parameter	Description	Version
tip	message: string, level: RuleLevel	Validation tip slot.	0.0.3
extra		Extra content slot located below the content area.	0.0.3
label		Custom label slot.	0.0.3
default		Form item content slot.	0.0.3

RuleLevel, FieldType, RuleTrigger, FormValidateResult

export type RuleLevel = 'error' | 'warning' | 'success' | 'normal'
export type FieldType = 'number' | 'string' | 'boolean' | 'array' | 'dict' | 'function' | 'date'
export type RuleTrigger = 'blur' | 'change' | 'input'

export type FormValidateResult = Promise<{
	isValid: boolean
	results: Record<
		string,
		PromiseSettledResult<{
			message: string
			level: RuleLevel
		}>
	>
}>

RestAttrs

import type { StyleValue } from 'vue'

export type VueClassValue = string | Record<string, any> | VueClassValue[]
export type VueStyleValue = StyleValue

export type RestAttrs = {
	style?: VueStyleValue | null
	class?: VueClassValue | null
	[x: string]: any
}