Form

Consists of input fields, selectors, radio buttons, checkboxes, and other controls, used for collecting, validating, and submitting data.

Basic Usage

Includes various layouts, sizes, and basic required field validation.

LargeDefaultSmall

Username

Age

Email

Basic Usage

Typical Form

Contains multiple types of form fields, demonstrating complex interactions and linked validation.

Activity Name

Activity Zone

Activity Location

Instant Delivery

Activity Type

Food/Restaurant online activityGround promotionOffline theme activity

Special Resource

Online brand sponsorshipOffline venue free

Satisfaction Rating

Activity Count

Activity Form

Typical Form

Inline Form

Setting layout="inline" allows form items to be arranged horizontally. Label and Input are precisely aligned vertically via Flex layout.

Approver

Activity Zone

Inline Form

Grid Layout

Utilizing the built-in 24-grid system, you can easily achieve complex responsive form layouts.

First Name

Last Name

Detailed Address

Grid Layout

Validation Feedback

After setting status-icon, validation result icons will be displayed on components like input fields and selectors.

Success Status

Loading

Error Status

Validation Icon

Nested Fields

Supports nested object path configuration, such as user.info.name.

City

Street

Nested Fields

Schema Driven (Dynamic Form)

Schema-driven form rendering with full support for grouping, grid layout, async data, conditional visibility, and custom slots.

Validation Notes

• required: true automatically adds mandatory constraints. For components like Switch (Boolean), it is recommended to use validator within rules for precise control and to avoid message conflicts.
• rules array supports fine-grained configuration of regex, length, custom functions, and other logic.
• formRef.validate() triggers complete validation for all registered fields.

Basic Schema

Configure the schema array to generate a form with required shorthand and footer slot bound to formRef.validate() for form validation.

Basic Info

Email

Account Type

Custom Slot

Slot

Basic Schema Usage

Advanced Schema (Async/Linkage/Collapse/Tooltip)

asyncOptions loads options asynchronously (auto-injects loading), props functions for field linkage, collapsible for collapsible groups, tooltip for field hints.

Product Config (Collapsible)

Category

Product

Agree to Terms

Remarks

Remark

Dynamic Linkage Demo

Reason Type

ID Card

Advanced Features

Field Type Extensions (divider / text / list / render)

• type: 'divider' inserts a separator line
• type: 'text' renders the field value as read-only, with emptyValue for placeholder when empty (default '-')
• type: 'list' enables dynamic add/remove sub-item lists. Use listSchema to define sub-fields and listProps for controls.
• render function for fully custom rendering

Basic Info

Name

Alice

Department

Engineering

Phone

Not set

Editable Content

City

Render

Current City: Not set

Field Type Extensions (divider / text / emptyValue / render)

Dynamic List (type: 'list')

Use type: 'list' to handle scenarios like a "contacts" dynamic list. listProps.max/min constrain how many items can be added or removed. Each row fully supports FormSchemaItem config including linked props and validation rules.

Contacts

Total 0 contacts (max 5)

Dynamic List

Scroll Offset (scroll-to-error-offset)

In pages with a fixed top navigation bar, scrolling to the first error item after validation failure might be obscured by the sticky header. Configure scroll-to-error-offset to set the top offset (in px):

The following is a long form. When you scroll to the bottom and click validate, the page will smoothly scroll back to the first error field. Thanks to the scroll-to-error-offset="64" configuration, the error field will not be obscured by the browser's top bar.

Form Item 1

Form Item 2 (I will trigger an error and be targeted)

Form Item 3

Form Item 4

Form Item 5

Form Item 6

Form Item 7

Form Item 8

Form Item 9

Form Item 10

Scroll Offset

Use in Nuxt

The Form component and its sub-components (FormItem, FormSchema) fully support Nuxt 3/4 SSR rendering. When used in a Nuxt project, all form components are automatically imported.

Username

Role

AdminUser

Use in Nuxt

SSR Notes:

• ✅ Form layout (horizontal, vertical, inline) remains perfectly consistent in SSR.
• ✅ Validation error state (is-error) and error messages support server-side rendering.
• ✅ Static validation rules take effect on the server (error styles present on first screen).
• ⚠️ Submission validation (validate method) and dynamic async validation are only available after client-side activation.
• 💡 It is recommended to use reactive to define the form model in Nuxt pages to maintain reactivity continuity.

SSR Safety

The internal IDs and ARIA attributes generated by the Form component are based on useId, ensuring that in highly nested form structures, the server and client HTML associations are perfectly consistent, triggering no hydration warnings.

API

Form Props

Prop	Description	Type	Default
model	Form data object	object	—
rules	Form validation rules	object	—
label-width	Label width	string | number	—
label-position	Label position	'left' | 'right' | 'top'	'right'
layout	Layout mode	'horizontal' | 'vertical' | 'inline'	'horizontal'
disabled	Whether to disable all components in the form	boolean	false
size	Unified size	'large' | 'default' | 'small'	'default'
status-icon	Whether to display validation result feedback icons in input fields	boolean	false
scroll-to-error	Whether to scroll to the first error item when validation fails	boolean	false
scroll-into-view-options	Scroll configuration items	object | boolean	{ behavior: 'smooth', block: 'center' }
scroll-to-error-offset	Top offset (px) for scroll-to-error, prevents overlap with sticky headers	number	0

Form Methods

Method	Description	Parameters
validate	Validates the form, supports partial validation	(props?: string | string[], callback?: Function)
resetFields	Resets the form, supports partial reset	(props?: string | string[])
clearValidate	Removes validation results for form items	(props?: string | string[])
scrollToField	Scrolls to a specified field	(prop: string)

FormItem Props

Prop	Description	Type	Default
prop	Form field model key, supports nested paths (a.b.c)	string	—
label	Label text	string	—
label-width	Label width	string | number	—
required	Whether it is required	boolean	false
rules	Validation rules	object | array	—
size	Configure size for the form item (overrides Form setting)	'large' | 'default' | 'small'	—
error-position	Error message alignment	'left' | 'center' | 'right'	'left'
show-message	Whether to show validation error messages	boolean	true
disabled	Disables current item (overrides Form setting)	boolean	false

FormSchema Props

Prop	Description	Type	Default
modelValue	Binding value (v-model)	object	—
schema	Form configuration items, supports grouping and grids	array	[]
formProps	Props passed through to YhForm (same as Form Props)	object	{}
gutter	Grid column spacing (px)	number	20

FormSchema Methods

Method	Description	Parameters
validate	Triggers form validation, supports partial	(fields?: string | string[], callback?: Function)
resetFields	Resets field values and validation state	(fields?: string | string[])
clearValidate	Clears validation results, supports partial	(fields?: string | string[])
scrollToField	Scrolls to specified field	(field: string)
getModel	Returns current form data snapshot	() => Record<string, unknown>
setFieldValue	Dynamically updates a single field value	(field: string, value: unknown)

FormSchema Slots

Slot Name	Description	Slot Props
field-{fieldName}	Custom rendering for a specific field	{ model, item, handleUpdate }
label-{fieldName}	Custom label rendering for a field	{ model, item }
footer	Form footer action area	{ model, formRef }
field-{listField}-{subField}	Custom render for a sub-field within a list row	{ row, index, item }
list-footer-{listField}	Area after the add-button in a list field	{ model, item }

FormSchemaItem (Configuration Item)

Prop	Description	Type	Default
field	Field name, supports nested paths (a.b.c)	string	—
label	Label name	string	—
type	Field type: 'default' normal, 'divider' separator, 'text' read-only, 'list' dynamic list	'default' | 'divider' | 'text' | 'list'	'default'
component	Component name (input, radio, select, etc.) or Vue Component object	string | Component	—
col	Grid span (1-24)	number	24
props	Props for internal component, supports functional linkage	object | (model) => object	—
formItemProps	Props passed through to form-item	object	—
required	Required (auto-adds required rule, no need to write rules)	boolean	false
rules	Validation rules (merged with required)	FormRule | FormRule[]	—
disabled	Whether disabled (supports functional linkage)	boolean | (model) => boolean	—
hidden	Whether hidden (supports functional linkage)	boolean | (model) => boolean	false
defaultValue	Default field value (applied when field value is undefined)	unknown	—
tooltip	Tooltip text shown next to field label	string	—
slots	Component slot config (key: slot name, value: component object)	object	—
render	Custom render function (lower priority than field-{name} slot)	(model) => VNode | Component	—
asyncOptions	Async options loader (auto-injects loading state)	() => Promise<object[]>	—
optionProp	Prop name for receiving async options data	string	'options'
emptyValue	Placeholder for type: 'text' when value is null/undefined/''	string	'-'
listSchema	Sub-field schema for type: 'list'	FormSchemaItem[]	—
listProps	Controls for type: 'list' (max/min/addButtonText/allowAdd/allowDelete)	object	—

FormSchemaGroup (Group Config)

Prop	Description	Type	Default
title	Group title	string	—
items	Form items within the group	FormSchemaItem[]	[]
props	Props passed through to fieldset	object	—
collapsible	Whether to enable collapsible feature	boolean	false
collapsed	Default collapsed state	boolean	false