ant-design-vue/components/form/index.en-US.md

---
category: Components
type: Data Entry
cols: 1
title: Form
cover: https://gw.alipayobjects.com/zos/alicdn/ORmcdeaoO/Form.svg
---

High performance Form component with data scope management. Including data collection, verification, and styles.

## When to use

- When you need to create an instance or collect information.
- When you need to validate fields in certain rules.

## Form Component

You can align the controls of a `form` using the `layout` prop：

- `horizontal`：to horizontally align the `label`s and controls of the fields. (Default)
- `vertical`：to vertically align the `label`s and controls of the fields.
- `inline`：to render form fields in one line.

## Form Item Component

A form consists of one or more form fields whose type includes input, textarea, checkbox, radio, select, tag, and more. A form field is defined using `<a-form-item />`.


## API

### Form

| Property | Description | Type | Default Value | Version |
| --- | --- | --- | --- | --- |
| model | data of form component | object |  |  |
| rules | validation rules of form | object |  |  |
| hideRequiredMark | Hide required mark of all form items | Boolean | false |  |
| layout | Define form layout | 'horizontal'\|'vertical'\|'inline' | 'horizontal' |  |
| labelAlign | text align of label of all items | 'left' \| 'right' | 'right' |  |
| labelCol | The layout of label. You can set `span` `offset` to something like `{span: 3, offset: 12}` or `sm: {span: 3, offset: 12}` same as with `<Col>` | [object](/components/grid/#Col) |  |  |
| wrapperCol | The layout for input controls, same as `labelCol` | [object](/components/grid/#Col) |  |  |
| colon | change default props colon value of Form.Item (only effective when prop layout is horizontal) | boolean | true |  |
| validateOnRuleChange | whether to trigger validation when the `rules` prop is changed | boolean | true |  |
| name | Form name. Will be the prefix of Field `id` | string | - | 2.0.0 |
| scrollToFirstError | Auto scroll to first failed field when submit | boolean \| [options](https://github.com/stipsan/scroll-into-view-if-needed/#options) | false | 2.0.0 |
| validateTrigger | Config field validate trigger | string \| string[] | `change` | 2.0.0 |

### Events

| Events Name | Description | Arguments | Version |
| --- | --- | --- | --- |
| submit | Defines a function will be called if form data validation is successful. | Function(e:Event) |  |
| validate | triggers after a form item is validated | name of the form item being validated, whether validation is passed and the error message if not |  |
| finish | Trigger after submitting the form and verifying data successfully | function(values) | - | 2.0.0 |
| finishFailed | Trigger after submitting the form and verifying data failed | function({ values, errorFields, outOfDate }) | - | 2.0.0 |

### Methods

| Method | Description | Parameters |
| --- | --- | --- |
| validate | Validate fields, it is same as validateFields | (nameList?: [NamePath](#NamePath)[]) => Promise |  |
| validateFields | Validate fields | (nameList?: [NamePath](#NamePath)[]) => Promise |  |
| scrollToField | Scroll to field position | (name: [NamePath](#NamePath), options: [[ScrollOptions](https://github.com/stipsan/scroll-into-view-if-needed/tree/ece40bd9143f48caf4b99503425ecb16b0ad8249#options)]) => void |  |
| resetFields | reset all the fields and remove validation result | — |
| clearValidate | clear validation message for certain fields. The parameter is name or an array of names of the form items whose validation messages will be removed. When omitted, all fields' validation messages will be cleared | Function(props: string \| array) |

### Form.Item

| Property | Description | Type | Default Value | Version |
| --- | --- | --- | --- | --- |
| name | a key of `model`. In the use of validate and resetFields method, the attribute is required | string |  | 2.0.0 |
| rules | validation rules of form | object \| array |  |  |
| autoLink | Whether to automatically associate form fields. In most cases, you can use automatic association. If the conditions for automatic association are not met, you can manually associate them. See the notes below. | boolean | true |  |
| colon | Used with `label`, whether to display `:` after label text. | boolean | true |  |
| extra | The extra prompt message. It is similar to help. Usage example: to display error message and prompt message at the same time. | string\|slot |  |  |
| hasFeedback | Used with `validateStatus`, this option specifies the validation status icon. Recommended to be used only with `Input`. | boolean | false |  |
| help | The prompt message. If not provided, the prompt message will be generated by the validation rule. | string\|slot |  |  |
| htmlFor | Set sub label `htmlFor`. | string |  |  |
| label | Label text | string\|slot |  |  |
| labelCol | The layout of label. You can set `span` `offset` to something like `{span: 3, offset: 12}` or `sm: {span: 3, offset: 12}` same as with `<Col>` | [object](/components/grid/#Col) |  |  |
| labelAlign | text align of label | 'left' \| 'right' | 'right' |  |
| required | Whether provided or not, it will be generated by the validation rule. | boolean | false |  |
| validateStatus | The validation status. If not provided, it will be generated by validation rule. options: 'success' 'warning' 'error' 'validating' | string |  |  |
| wrapperCol | The layout for input controls, same as `labelCol` | [object](/components/grid/#Col) |  |  |
| validateFirst | Whether stop validate on first rule of error for this field. | boolean | false |  |
| validateTrigger | When to validate the value of children node | string \| string[] | `change` |  |

#### Note

Form.Item will hijack the only child element and listen to the `blur` and`change` events to achieve the purpose of automatic verification, so please ensure that the form field is not wrapped by other elements. If there are multiple child elements, only the first child element will be monitored for changes.

If the form field to be monitored does not meet the conditions for automatic monitoring, you can associate the form field as follows:

```html
<a-form-item name="form.name" ref="name" :autoLink="false">
  <a-input v-model:value="other" />
  <span>hahha</span>
  <div>
    <a-input
      v-model:value="form.name"
      @blur="() => {$refs.name.onFieldBlur()}"
      @change="() => {$refs.name.onFieldChange()}"
    />
  </div>
</a-form-item>
```

### Validation Rules

| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| trigger | When to validate the value of children node. | 'blur' \| 'change' \| `['change', 'blur']` | - |
| enum | validate a value from a list of possible values | string | - |
| len | validate an exact length of a field | number | - |
| max | validate a max length of a field | number | - |
| message | validation error message | string | - |
| min | validate a min length of a field | number | - |
| pattern | validate from a regular expression | RegExp | - |
| required | indicates whether field is required | boolean | `false` |
| transform | transform a value before validation | function(value) => transformedValue:any | - |
| type | built-in validation type, [available options](https://github.com/yiminghe/async-validator#type) | string | 'string' |
| validator | custom validate function (Note: [callback must be called](https://github.com/ant-design/ant-design/issues/5155)) | function(rule, value, callback) | - |
| whitespace | treat required fields that only contain whitespace as errors | boolean | `false` |

See more advanced usage at [async-validator](https://github.com/yiminghe/async-validator).


### useForm (v2.2)

`useForm` is a method that can run independently of the Form component. It uses the Vue response mechanism to monitor and verify data, and returns the verification result. You can bind the verification result to any component, `Form. Item` only displays the results.

The following versions need to be provided separately by `@ant-design-vue/use` library, it is not recommended to continue to use, you should upgrade to version 2.2+ as soon as possible


```ts
import { Form } from 'ant-design-vue';
const useForm = Form.useForm;

useForm(modelRef, ruleRef, [options]);

```

参数说明：

```ts
/*
 modelRef`, `ruleRef` must be responsive data
*/

interface Props {
  [key: string]: any;
}
function useForm(
  modelRef: Props | Ref<Props>,
  rulesRef?: Props | Ref<Props>,
  options?: {
    immediate?: boolean;
    deep?: boolean;
    validateOnRuleChange?: boolean;
    debounce?: DebounceSettings;
  },
): {
  modelRef: Props | Ref<Props>;
  rulesRef: Props | Ref<Props>;
  initialModel: Props;
  validateInfos: validateInfos;
  resetFields: (newValues?: Props) => void;
  validate: <T = any>(names?: namesType, option?: validateOptions) => Promise<T>;
  validateField: (
    name?: string,
    value?: any,
    rules?: [Record<string, unknown>],
    option?: validateOptions,
  ) => Promise<RuleError[]>;
  mergeValidateInfo: (items: ValidateInfo | ValidateInfo[]) => ValidateInfo;
  clearValidate: (names?: namesType) => void;
}
```