--- category: Components type: Data Entry cols: 1 title: Form --- 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. ## API ### Form | Property | Description | Type | Default | | --- | --- | --- | --- | | component | Set the Form rendering element. Do not create a DOM node for `false` | ComponentType \| false | form | | colon | Configure the default value of `colon` for Form.Item. Indicates whether the colon after the label is displayed (only effective when prop layout is horizontal) | boolean | true | | fields | Control of form fields through state management (such as redux). Not recommended for non-strong demand. View [example](#components-form-demo-global-state) | [FieldData](#FieldData)\[] | - | | form | Form control instance created by `Form.useForm()`. Automatically created when not provided | [FormInstance](#FormInstance) | - | | hideRequiredMark | Hide required mark for all form items | boolean | false | | initialValues | Set value by Form initialization or reset | object | - | | labelAlign | text align of label of all items | `left` \| `right` | `right` | | labelCol | label layout, like `` component. Set `span` `offset` value like `{span: 3, offset: 12}` or `sm: {span: 3, offset: 12}` | [object](/components/grid/#Col) | - | | layout | Form layout | `horizontal` \| `vertical` \| `inline` | `horizontal` | | name | Form name. Will be the prefix of Field `id` | string | - | | scrollToFirstError | Auto scroll to first failed field when submit | false | - | | size | Set field component size (antd components only) | `small` \| `middle` \| `large` | - | | validateMessages | Validation prompt template, description [see below](#validateMessages) | [ValidateMessages](https://github.com/react-component/field-form/blob/master/src/utils/messages.ts) | - | | wrapperCol | The layout for input controls, same as `labelCol` | [object](/components/grid/#Col) | - | | onFinish | Trigger after submitting the form and verifying data successfully | Function(values) | - | | onFinishFailed | Trigger after submitting the form and verifying data failed | Function({ values, errorFields, outOfDate }) | - | | onFieldsChange | Trigger when field updated | Function(changedFields, allFields) | - | | onValuesChange | Trigger when value updated | Function(changedValues, allValues) | - | ### validateMessages Form provides [default verification error messages](https://github.com/react-component/field-form/blob/master/src/utils/messages.ts). You can modify the template by configuring `validateMessages` property. A common usage is to configure localization: ```jsx const validateMessages = { required: "'${name}' is required!", // ... };
; ``` Besides, [ConfigProvider](/components/config-provider/) also provides a global configuration scheme that allows for uniform configuration error notification templates: ```jsx const validateMessages = { required: "'${name}' is Required!", // ... }; ; ``` ## Form.Item Form field component for data bidirectional binding, validation, layout, and so on. | Property | Description | Type | Default | Version | | --- | --- | --- | --- | --- | | colon | Used with `label`, whether to display `:` after label text. | boolean | true | | | dependencies | Set the dependency field. See [below](#dependencies) | [NamePath](#NamePath)[] | - | | | extra | The extra prompt message. It is similar to help. Usage example: to display error message and prompt message at the same time | string\|ReactNode | - | | | getValueFromEvent | Specify how to get value from event or other onChange arguments | (..args: any[]) => any | - | | | getValueProps | Additional props with sub component | (value: any) => any | - | 4.2.0 | | 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\|ReactNode | - | | | htmlFor | Set sub label `htmlFor` | string | - | | | initialValue | Config sub default value. Form `initialValues` get higher priority when conflict | string | - | 4.2.0 | | noStyle | No style for `true`, used as a pure field control | boolean | false | | | label | Label text | string\|ReactNode | - | | | labelAlign | text align of label | `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 ``. You can set `labelCol` on Form. If both exists, use Item first | [object](/components/grid/#Col) | - | | | name | Field name, support array | [NamePath](#NamePath) | - | | | normalize | Normalize value from component value before passing to Form instance | (value, prevValue, prevValues) => any | - | | | required | Display required style. It will be generated by the validation rule | boolean | false | | | rules | Rules for field validation. Click [here](#components-form-demo-basic) to see an example | [Rule](#Rule)[] | - | | | shouldUpdate | Custom field update logic. See [below](#shouldUpdate) | boolean \| (prevValue, curValue) => boolean | false | | | trigger | When to collect the value of children node | string | onChange | | | validateFirst | Whether stop validate on first rule of error for this field | boolean | false | | | validateStatus | The validation status. If not provided, it will be generated by validation rule. options: 'success' 'warning' 'error' 'validating' | string | - | | | validateTrigger | When to validate the value of children node | string \| string[] | onChange | | | valuePropName | Props of children node, for example, the prop of Switch is 'checked'. This prop is an encapsulation of `getValueProps`, which will be invalid after customizing `getValueProps` | string | 'value' | | | wrapperCol | The layout for input controls, same as `labelCol`. You can set `wrapperCol` on Form. If both exists, use Item first | [object](/components/grid/#Col) | - | | After wrapped by `Form.Item` with `name` property, `value`(or other property defined by `valuePropName`) `onChange`(or other property defined by `trigger`) props will be added to form controls, the flow of form data will be handled by Form which will cause: 1. You shouldn't use `onChange` on each form control to **collect data**(use `onValuesChange` of Form), but you can still listen to `onChange`. 2. You cannot set value for each form control via `value` or `defaultValue` prop, you should set default value with `initialValues` of Form. Note that `initialValues` cannot be updated by `setState` dynamiclly, you should use `setFieldsValue` in that situation. 3. You shouldn't call `setState` manually, please use `form.setFieldsValue` to change value programmatically. ### dependencies Used when there are dependencies between fields. If a field has the `dependencies` prop, this field will automatically trigger updates and validations when upstream is updated. A common scenario is a user registration form with "password" and "confirm password" fields. The "Confirm Password" validation depends on the "Password" field. After setting `dependencies`, the "Password" field update will re-trigger the validation of "Check Password". You can refer [examples](#components-form-demo-register). ### shouldUpdate Form updates only the modified field-related components for performance optimization purposes by incremental update. In most cases, you only need to write code or do validation with the [`dependencies`](#dependencies) property. In some specific cases, such as when a new field option appears with a filed value changed, or you just want to keep some area updating by form update, you can modify the update logic of Form.Item via the `shouldUpdate`. When `shouldUpdate` is `true`, any Form update will cause the Form.Item to be re-rendered. This is very helpful for custom rendering some areas: ```jsx {() => { return
{JSON.stringify(form.getFieldsValue(), null, 2)}
; }}
``` You can ref [example](#components-form-demo-horizontal-login) to see detail. When `shouldUpdate` is a function, it will be called by form values update. Providing original values and current value to compare. This is very helpful for rendering additional fields based on values: ```jsx prevValues.additional !== curValues.additional}> {() => { return ( ); }} ``` You can ref [example](#components-form-demo-control-hooks) to see detail. ## Form.List Provides array management for fields. | Property | Description | Type | Default | | --- | --- | --- | --- | | name | Field name, support array | [NamePath](#NamePath) | - | | children | Render function | (fields: Field[], operation: { add, remove, move }) => React.ReactNode | - | ```tsx {fields => (
{fields.map(field => ( ))}
)}
``` ## Form.Provider Provide linkage between forms. If a sub form with `name` prop update, it will auto trigger Provider related events. See [example](#components-form-demo-form-context). | Property | Description | Type | Default | | --- | --- | --- | --- | | onFormChange | Triggered when a sub form field updates | Function(formName: string, info: { changedFields, forms }) | - | | onFormFinish | Triggered when a sub form submits | Function(formName: string, info: { values, forms }) | - | ```jsx { if (name === 'form1') { // Do something... } }} > ...
...
``` ### FormInstance | Name | Description | Type | | --- | --- | --- | | getFieldValue | Get the value by the field name | (name: [NamePath](#NamePath)) => any | | getFieldsValue | Get values by a set of field names. Return according to the corresponding structure | (nameList?: [NamePath](#NamePath)[], filterFunc?: (meta: { touched: boolean, validating: boolean }) => boolean) => any | | getFieldError | Get the error messages by the field name | (name: [NamePath](#NamePath)) => string[] | | getFieldsError | Get the error messages by the fields name. Return as an array | (nameList?: [NamePath](#NamePath)[]) => FieldError[] | | isFieldTouched | Check if a field has been operated | (name: [NamePath](#NamePath)) => boolean | | isFieldsTouched | Check if fields have been operated. Check if all fields is touched when `allTouched` is `true` | (nameList?: [NamePath](#NamePath)[], allTouched?: boolean) => boolean | | isFieldValidating | Check fields if is in validating | (name: [NamePath](#NamePath)) => boolean | | resetFields | Reset fields to `initialValues` | (fields?: [NamePath](#NamePath)[]) => void | | scrollToField | Scroll to field position | (name: [NamePath](#NamePath), options: [[ScrollOptions](https://github.com/stipsan/scroll-into-view-if-needed/blob/ece40bd9143f48caf4b99503425ecb16b0ad8249/src/types.ts#L10)]) => void | | setFields | Set fields status | (fields: [FieldData](#FieldData)[]) => void | | setFieldsValue | Set fields value | (values) => void | | submit | Submit the form. It's same as click `submit` button | () => void | | validateFields | Validate fields | (nameList?: [NamePath](#NamePath)[]) => Promise | #### validateFields return sample ```jsx validateFields() .then(values => { /* values: { username: 'username', password: 'password', } */ }) .catch(errorInfo => { /* errorInfo: { values: { username: 'username', password: 'password', }, errorFields: [ { password: ['username'], errors: ['Please input your Password!'] }, ], outOfDate: false, } */ }); ``` ### Interface #### NamePath `string | number | (string | number)[]` #### FieldData | Name | Description | Type | | ---------- | ------------------------ | ----------------------- | | touched | Whether is operated | boolean | | validating | Whether is in validating | boolean | | errors | Error messages | string[] | | name | Field name path | [NamePath](#NamePath)[] | | value | Field value | any | #### Rule Rule support config object, and also support function to get config object: ```tsx type Rule = RuleConfig | ((form: FormInstance) => RuleConfig); ``` | Name | Description | Type | | --- | --- | --- | | enum | Match enum value | any[] | | len | Length of string, number, array | number | | max | Max length of string, number, array | number | | message | Error message. Will auto generate by [template](#validateMessages) if not provided | string | | min | Min length of string, number, array | number | | pattern | Regex pattern | RegExp | | required | Required field | boolean | | transform | Transform value to the rule before validation | (value) => any | | type | Normally `string` \|`number` \|`boolean` \|`url` \| `email`. More type to ref [here](https://github.com/yiminghe/async-validator#type) | string | | validator | Customize validation rule. Accept Promise as return. [example](#components-form-demo-register)参考 | ([rule](#Rule), value) => Promise | | whitespace | Failed if only has whitespace | boolean | | validateTrigger | Set validate trigger event. Must be the sub set of `validateTrigger` in Form.Item | string \| string[] | ## Migrate to v4 If you are a user of v3, you can ref [migrate doc](/components/form/v3)。 ## FAQ ### Custom validator not working It may be caused by your `validator` if it has some errors that prevents `callback` to be called. You can use `async` instead or use `try...catch` to catch the error: ```jsx validator: async (rule, value) => { throw new Error('Something wrong!'); } // or validator(rule, value, callback) => { try { throw new Error('Something wrong!'); } catch (err) { callback(err); } } ``` ### Why is there a form warning when used in Modal? > Warning: Instance created by `useForm` is not connect to any Form element. Forget to pass `form` prop? Before Modal open, children elements do not exist in the view. You can set `forceRender` on Modal to pre-render its children. Click [here](https://codesandbox.io/s/antd-reproduction-template-ibu5c) to view an example. ### Why component `defaultValue` not working when inside Form.Item? Components inside Form.Item with name property will turn into controlled mode, that makes `defaultValue` does not work anymore. Please try `initialValues` of Form to set default value. ### Why `resetFields` will re-mount component? `resetFields` will re-mount component under Field to clean up customize component side effect(like asyn data, cached state, etc.). It's by design. ### Difference between Form initialValues and Item initialValue? In most case, we always recommend to use Form `initialValues`. Use Item `initialValue` only when dynamic field usage. Priority follow the rules: 1. Form `initialValues` is the first priority 2. Field `initialValue` is secondary \*. Not work when multiple Item with same `name` setting the `initialValue` ### Why `onFieldsChange` trigger three times on change when field set `rules`? Validating is also part of the value updating. It pass follow steps: 1. Trigger value change 2. Rule validating 3. Rule validated In each `onFieldsChange`, you will get `false` > `true` > `false` with `isFieldValidating`.