Form

TuiForm provides a complete solution for data collection, validation, and submission. It integrates the async-validator library under the hood, supporting powerful and flexible asynchronous validation rules.

Basic Usage

The core function of the TuiForm component is to manage the data model (model) and validation rules (rules). By binding the corresponding data field through the prop property in TuiFormItem, the validation logic is automatically linked.

<script setup>
import { reactive, ref } from 'vue';

const formRef = ref(null);

const form = reactive({
  name: '',
  type: '',
  desc: ''
});

const rules = reactive({
  name: [
    { required: true, message: 'Please input activity name', trigger: 'blur' },
    { min: 3, max: 20, message: 'Length should be 3 to 20 characters', trigger: 'blur' }
  ],
  type: [
    { required: true, message: 'Please select activity type', trigger: 'change' }
  ]
});

const onSubmit = async () => {
  try {
    const valid = await formRef.value.validate();
    if (valid) {
      console.log('Submit Success:', form);
    }
  } catch (error) {
    console.log('Validation Failed:', error);
  }
};

const onReset = () => {
  formRef.value.resetFields();
};
</script>

<template>
  <TuiForm ref="formRef" :model="form" :rules="rules" labelWidth="120px">
    <TuiFormItem label="Activity Name" prop="name">
      <TuiInput v-model="form.name" placeholder="Please input name" />
    </TuiFormItem>
    
    <TuiFormItem label="Activity Type" prop="type">
      <TuiSelect v-model="form.type" :options="[{label:'Online',value:'online'}]" />
    </TuiFormItem>
    
    <TuiFormItem label="Notes" prop="desc">
      <TuiInput type="textarea" v-model="form.desc" />
    </TuiFormItem>

    <TuiFormItem>
      <TuiButton type="primary" @click="onSubmit">Submit</TuiButton>
      <TuiButton @click="onReset">Reset</TuiButton>
    </TuiFormItem>
  </TuiForm>
</template>

Layout and Alignment

Label Position

The position of the label can be controlled via the labelPosition property:

• right (default): Right-aligned.
• left: Left-aligned.
• top: Top-aligned (the label is located above the input box).

<TuiForm labelPosition="top" :model="form">...</TuiForm>

Inline Form

By setting inline to true, the form items will be arranged horizontally. This is commonly used for top search bars.

<TuiForm inline :model="queryForm">
  <TuiFormItem label="Username">
    <TuiInput v-model="queryForm.user" />
  </TuiFormItem>
  <TuiFormItem>
    <TuiButton type="primary">Query</TuiButton>
  </TuiFormItem>
</TuiForm>

Grid Layout

TuiForm can work perfectly with TuiRow and TuiCol to achieve complex row and column layouts.

<TuiForm :model="form">
  <TuiRow :gutter="20">
    <TuiCol :span="12">
      <TuiFormItem label="Start Time" prop="startTime">...</TuiFormItem>
    </TuiCol>
    <TuiCol :span="12">
      <TuiFormItem label="End Time" prop="endTime">...</TuiFormItem>
    </TuiCol>
  </TuiRow>
</TuiForm>

Global Control

TuiForm provides a series of properties for unified configuration distribution, reducing repetitive code:

• size: Uniformly controls the size of internal components that support the size attribute (large, default, small).
• disabled: Globally disables all components within the form.
• labelWidth: Sets a unified label width.
• labelSuffix: Sets a unified label suffix (e.g., : or -).
• asteriskPosition: Position of the required asterisk (left, right).

Form Item Configuration

In addition to inheriting the global configuration of the Form, TuiFormItem also supports individual configurations:

• contentAlign: Controls the alignment of the content area (left, center, right). This is very useful for scenarios where a button group needs to be displayed on the right.

<TuiFormItem contentAlign="right">
  <TuiButton type="primary" @click="submit">Submit</TuiButton>
  <TuiButton @click="cancel">Cancel</TuiButton>
</TuiFormItem>

API Reference

TuiForm Props

Property	Type	Default	Description
model	Object	{}	Core data object. Form data source.
rules	Object	{}	Validation rules object. Based on async-validator.
inline	Boolean	false	Whether it is in inline form mode.
labelPosition	String	'right'	Label alignment. Options: left, right, top.
labelWidth	String/Number	150	Label width.
labelSuffix	String	':'	Label suffix character.
labelHide	Boolean	false	Whether to hide all labels.
asteriskHide	Boolean	false	Whether to hide the required asterisk.
asteriskPosition	String	'left'	Asterisk position. Options: left, right.
showMessage	Boolean	true	Whether to show validation error messages.
inlineMessage	Boolean	false	Whether to show validation messages in an inline format.
size	String	'default'	Global size. Options: large, default, small.
disabled	Boolean	false	Globally disable the form.
validateOnRuleChange	Boolean	true	Whether to trigger validation immediately after the rules property changes.
scrollToError	Boolean	false	Whether to scroll to the first error item when validation fails.
scrollIntoViewOptions	Object/Boolean	true	Scroll configuration (same as native scrollIntoView parameters).

TuiForm Methods (Expose)

Method Name	Description	Parameters
validate	Validates the entire form. Returns a Promise.	(callback: Function)
validateField	Validates partial fields.	`(props: String
resetFields	Resets form fields to initial values and removes validation results.	-
clearValidate	Clears validation information (does not reset values).	`(props: String
scrollToField	Scrolls to a specified field.	(prop: String)

TuiForm Emits

Event Name	Description	Callback Parameters
validate	Triggered after any form item is validated.	(prop: String, isValid: Boolean, message: String)

TuiFormItem Props

Property	Type	Default	Description
prop	String/Array	-	Key name corresponding to model. Used for validation and resetting.
label	String	-	Label text.
required	Boolean	false	Whether it is required (if not set, it is automatically generated based on rules).
error	String	-	Manually set error message for the form field.
validateStatus	String	-	Manually set validation status. Options: error, validating, success.
for	String	-	Specifies the for attribute of the native label.
contentAlign	String	null	Alignment of the content area. Options: left, center, right.

TuiFormItem Methods (Expose)

Method Name	Description
resetField	Resets the current field.
clearValidate	Clears validation information for the current field.
validateMessage	Current validation error message.
validateState	Current validation status.