DynamicForm

Dynamic form component for quickly building form interfaces based on configuration.

TIP

In addition to the full dynamic form component, we also provide a standalone EzFormItem component that can be used to build custom form layouts.

Basic Usage

Component Types

Form Validation

Custom Slots

Attributes

Attribute	Description	Type	Required	Default
model-value	Initial form data	Record	No	-
items	Form configuration items	FormItemConfig[]	Yes	[]
cols	Grid layout columns	number	No	1
gutter	Grid spacing	number	No	20
formProps	el-form attributes	Partial	No	-

FormItemConfig

Attribute	Description	Type	Required	Default
prop	Field name	string	Yes	-
label	Label	string	No	-
type	Component type	FormItemType | string	No	-
defaultValue	Default value	any	No	-
rules	Validation rules	FormItemRule	No	-
required	Required	boolean	No	false
requiredMessage	Required message	string	No	-
span	Occupied grid columns	number	No	-
hidden	Hidden	boolean	No	false
disabled	Disabled	boolean	No	false
placeholder	Placeholder	string	No	-
options	Option configuration	FormItemOption[]	No	-
attrs	Component attributes (pass through to specific component)	Record	No	-
component	Custom component	Component	No	-
itemAttrs	Additional el-form-item attributes	Record	No	-
show	Linkage display condition	Function	No	-
disabledWhen	Linkage disable condition	Function	No	-

Data Initialization Priority

• model-value: External initial data, highest priority
• defaultValue: Default value in config, only takes effect when field not exists in model-value

Data Flow Design

This component uses unidirectional data flow + method control design:

• model-value is only for initialization, no two-way binding
• Use getFormData() to get form data on demand (e.g., on submit)
• Use setFormData() to explicitly set data (auto clear validation)
• This design ensures clear data flow and optimal performance, suitable for complex form scenarios

Breaking change

As of this version the component no longer automatically watches or two-way-syncs model-value (it will not emit update:modelValue).

• To update the form from outside, call the component instance method setFormData(data, merge?: boolean).
• To read the latest form values, call getFormData() (for example on submit).
• If your code relied on v-model two-way binding previously, migrate to using a ref and the methods above.

This change avoids high-frequency two-way synchronization and improves performance for complex forms.

FormItemType

Name	Description
INPUT	Input
TEXTAREA	Textarea
NUMBER	Number Input
PASSWORD	Password Input
SELECT	Select (wrapped component)
RADIO	Radio (wrapped component)
CHECKBOX	Checkbox (wrapped component)
DATE	Date Picker
DATETIME	DateTime Picker
DATERANGE	Date Range
DATETIMERANGE	DateTime Range
TIME	Time Picker
TIMERANGE	Time Range
UPLOAD_IMAGES	Image Upload (wrapped component)
SWITCH	Switch
TREE_SELECT	Tree Select
CASCADER	Cascader
TREE	Tree
SLIDER	Slider
RATE	Rate

Methods

Method	Description	Type
validate	Validate form	Function
validateField	Validate specified fields	Function
clearValidate	Clear validation	Function
resetFields	Reset form (reset to initial data)	Function
getFormData	Get form data (call on demand)	Function
setFormData	Set form data (auto clear validation, support merge or replace)	Function

Slots

Name	Description	Parameters
[prop]	Custom form item content	{ item: FormItemConfig, value: any, formData: Record }
label-[prop]	Custom form item label	{ item: FormItemConfig }