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 modes remain consistent between SSR output and client hydration.
• Static validation styles and error text can be rendered on the server.
• Instance methods such as validate and async validation run after client activation.
• Use a reactive form model in Nuxt pages to keep bindings and validation state synchronized.

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

Props

Form

Prop	Description	Type	Default
model	Reactive form model object.	Record<string, unknown>	Required
rules	Validation rules object.	YhFormRules	{}
label-width	Label width.	string | number	''
label-position	Label alignment mode.	'left' | 'right' | 'top'	'right'
label-suffix	Suffix appended after each label.	string	''
show-message	Whether validation messages are displayed.	boolean	true
scroll-to-error	Whether the first invalid field is scrolled into view after validation fails.	boolean	false
scroll-into-view-options	Native scrollIntoView options used when scrolling to an invalid field.	boolean | ScrollIntoViewOptions	false
scroll-to-error-offset	Top offset used by scroll-to-error.	number	0
disabled	Whether all form controls inherit the disabled state.	boolean	false
hide-required-asterisk	Whether required marks are hidden.	boolean	false
size	Shared control size.	'large' | 'default' | 'small'	'default'
status-icon	Whether validation status icons are shown.	boolean	false
layout	Form layout mode.	'horizontal' | 'vertical' | 'inline'	'horizontal'
theme-overrides	Component-level theme overrides for YhForm.	ComponentThemeVars	undefined

Form Item

Prop	Description	Type	Default
prop	Field path in the parent form model. Supports nested paths such as user.profile.name.	string	''
label	Label text.	string	''
label-width	Label width override.	string | number	''
required	Whether the item is required.	boolean	false
rules	Item-level validation rules.	YhFormRule | YhFormRule[]	[]
show-message	Whether this item displays validation error text.	boolean	true
size	Size override for the current item.	'large' | 'default' | 'small' | ''	''
validate-trigger	Validation trigger override.	string | string[]	''
error-position	Alignment of the validation message.	'left' | 'center' | 'right'	'left'
disabled	Whether the current item is disabled.	boolean	false
validate-status	Manual validation status override.	'' | 'success' | 'error' | 'validating'	''
error	Manual validation message override.	string	''
theme-overrides	Component-level theme overrides for YhFormItem.	ComponentThemeVars	undefined

Form Schema

Prop	Description	Type	Default
modelValue	Bound schema model value.	Record<string, unknown>	Required
schema	Schema configuration list.	(YhFormSchemaItem | YhFormSchemaGroup)[]	[]
formProps	Props forwarded to YhForm.	Partial<YhFormProps>	{}
gutter	Grid spacing in pixels.	number	20

Events

Form

Event Name	Description	Type
validate	Triggered after a validation run completes.	(isValid: boolean, invalidFields?: Record<string, unknown>) => void

Form Item

Current component does not expose component events.

Form Schema

Event Name	Description	Type
update:modelValue	Triggered when the schema model changes.	(value: Record<string, unknown>) => void
submit	Triggered when the internal form is submitted.	(value: Record<string, unknown>) => void
change	Triggered when a schema field changes.	(field: string, value: unknown, model: Record<string, unknown>) => void
validate	Forwarded form validation result.	(isValid: boolean, invalidFields?: Record<string, unknown>) => void

Slots

Form

Slot Name	Description	Parameters
default	Form content.	-

Form Item

Slot Name	Description	Parameters
default	Form control content.	-
label	Custom label content.	-

Form Schema

Slot Name	Description	Parameters
field-{fieldName}	Custom rendering for a specific schema field.	{ model, item, handleUpdate }
label-{fieldName}	Custom label rendering for a specific schema field.	{ model, item }
footer	Footer action area.	{ model, formRef }
field-{listField}-{subField}	Custom renderer for a list-row sub-field.	{ row, index, item }
list-footer-{listField}	Content rendered after the add button of a list field.	{ model, item }

Expose

Form

Name	Description	Type
validate	Validates the whole form or specific fields.	(props?: string | string[] | ((isValid: boolean, invalidFields?: Record<string, unknown>) => void), callback?: (isValid: boolean, invalidFields?: Record<string, unknown>) => void) => Promise<boolean>
resetFields	Resets all fields or specific fields.	(props?: string | string[]) => void
clearValidate	Clears validation results.	(props?: string | string[]) => void
scrollToField	Scrolls to a specific field.	(prop: string) => void

Form Item

Name	Description	Type
validate	Validates the current form item.	(trigger?: string, callback?: (isValid: boolean) => void) => Promise<boolean>
resetField	Resets the current item value and validation state.	() => void
clearValidate	Clears the current item validation state.	() => void
validateStatus	Current validation status.	ComputedRef<'' | 'success' | 'error' | 'validating'>
validateMessage	Current validation message.	ComputedRef<string>
size	Resolved item size.	ComputedRef<string>

Form Schema

Name	Description	Type
validate	Validates the schema form or specific fields.	(fields?: string | string[], callback?: (isValid: boolean) => void) => Promise<boolean | undefined>
resetFields	Resets schema fields.	(fields?: string | string[]) => void
clearValidate	Clears schema validation results.	(fields?: string | string[]) => void
scrollToField	Scrolls to a schema field.	(field: string) => void
getModel	Returns the current schema model snapshot.	() => Record<string, unknown>
setFieldValue	Updates a single schema field value.	(field: string, value: unknown) => void
formRef	Underlying YhForm instance ref.	Ref<YhFormInstance | undefined>

Types

Form Schema Item

Prop	Description	Type	Default
field	Field path, supports nested paths.	string	Required
label	Field label.	string	undefined
type	Schema item type.	'default' | 'divider' | 'text' | 'list'	'default'
component	Component name or Vue component.	string | Component	undefined
props	Props passed to the rendered field component. Supports a function form.	Record<string, unknown> | (model: Record<string, unknown>) => Record<string, unknown>	undefined
formItemProps	Extra props passed to YhFormItem.	Partial<YhFormItemProps>	undefined
rules	Validation rules or a rule factory based on the current model.	YhFormRule[] | (model: Record<string, unknown>) => YhFormRule[]	undefined
required	Required shorthand or required factory.	boolean | (model: Record<string, unknown>) => boolean	false
hidden	Whether the field is hidden. Supports a function form.	boolean | (model: Record<string, unknown>) => boolean	false
disabled	Whether the field is disabled. Supports a function form.	boolean | (model: Record<string, unknown>) => boolean	undefined
slots	Slot component mapping used by schema rendering.	Record<string, unknown>	undefined
col	Grid span from 1 to 24.	number	24
span	Custom grid-column span.	number	undefined
render	Custom render function.	(model: Record<string, unknown>) => VNode | Component | null	undefined
asyncOptions	Async option loader for option-based components.	() => Promise<Record<string, unknown>[]>	undefined
optionProp	Prop name that receives async options.	string	'options'
defaultValue	Default field value used when the model field is undefined.	unknown	undefined
tooltip	Tooltip text displayed next to the label.	string	undefined
emptyValue	Placeholder used by type: 'text' when the value is empty.	string	'-'
listSchema	Child schema used by type: 'list'.	YhFormSchemaItem[]	undefined
listProps	Controls used by type: 'list'.	{ addButtonText?: string; allowDelete?: boolean | ((model: Record<string, unknown>, index: number) => boolean); allowAdd?: boolean | ((model: Record<string, unknown>) => boolean); max?: number; min?: number }	undefined

Form Schema Group

Prop	Description	Type	Default
title	Group title.	string	undefined
items	Items rendered inside the group.	YhFormSchemaItem[]	[]
props	Extra props passed to the wrapping fieldset.	Record<string, unknown>	undefined
collapsible	Whether the group supports collapse/expand interaction.	boolean	false
collapsed	Initial collapsed state.	boolean	false

Theme Variables

YhForm and YhFormItem support themeOverrides. Their runtime styles consume the following component variables:

Variable	Description	Default
--yh-form-item-height	Base height used by form items and aligned controls.	32px
--yh-form-item-margin-bottom	Bottom spacing between form items.	22px
--yh-form-label-font-size	Form label font size.	14px

YhFormSchema mainly reuses form and global theme tokens and does not define extra dedicated component variables.

Type Exports

Name	Description
YhFormProps	Props type for YhForm
YhFormItemProps	Props type for YhFormItem
YhFormSchemaProps	Props type for YhFormSchema
YhFormSchemaItem	Schema form item type
YhFormSchemaGroup	Schema form group type
YhFormRule	Single validation rule type
YhFormRules	Form rules collection type
YhFormInstance	Public instance type for YhForm
YhFormItemInstance	Public instance type for YhFormItem
YhFormSchemaInstance	Public instance type for YhFormSchema