contributors
- Components Overview
- Changelogv6.1.4
- General
- Layout
- Navigation
- Data Entry
- Data Display
- Feedback
- Other
Common props ref:Common props
| Property | Description | Type | Default | Version |
|---|---|---|---|---|
| classNames | Customize class for each semantic structure inside the component. Supports object or function. | Record<SemanticDOM, string> | (info: { props })=> Record<SemanticDOM, string> | - | |
| 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 | |
| disabled | Set form component disable, only available for antd components | boolean | false | 4.21.0 |
| component | Set the Form rendering element. Do not create a DOM node for false | ComponentType | false | form | |
| fields | Control of form fields through state management (such as redux). Not recommended for non-strong demand. View example | FieldData[] | - | |
| form | Form control instance created by Form.useForm(). Automatically created when not provided | FormInstance | - | |
| feedbackIcons | Can be passed custom icons while Form.Item element has hasFeedback | FeedbackIcons | - | 5.9.0 |
| initialValues | Set value by Form initialization or reset | object | - | |
| labelAlign | The text align of label of all items | left | right | right | |
| labelWrap | whether label can be wrap | boolean | false | 4.18.0 |
| labelCol | Label layout, like <Col> component. Set span offset value like {span: 3, offset: 12} or sm: {span: 3, offset: 12} | object | - | |
| layout | Form layout | horizontal | vertical | inline | horizontal | |
| name | Form name. Will be the prefix of Field id | string | - | |
| preserve | Keep field value even when field removed. You can get the preserve field value by getFieldsValue(true) | boolean | true | 4.4.0 |
| requiredMark | Required mark style. Can use required mark or optional mark. You can not config to single Form.Item since this is a Form level config | boolean | optional | ((label: ReactNode, info: { required: boolean }) => ReactNode) | true | renderProps: 5.9.0 |
| scrollToFirstError | Auto scroll to first failed field when submit | boolean | Options | { focus: boolean } | false | focus: 5.24.0 |
| size | Set field component size (antd components only) | small | middle | large | - | |
| styles | Customize inline style for each semantic structure inside the component. Supports object or function. | Record<SemanticDOM, CSSProperties> | (info: { props })=> Record<SemanticDOM, CSSProperties> | - | |
| validateMessages | Validation prompt template, description see below | ValidateMessages | - | |
| validateTrigger | Config field validate trigger | string | string[] | onChange | 4.3.0 |
| variant | Variant of components inside form | outlined | borderless | filled | underlined | outlined | 5.13.0 | underlined: 5.24.0 |
| wrapperCol | The layout for input controls, same as labelCol | object | - | |
| onFieldsChange | Trigger when field updated | function(changedFields, allFields) | - | |
| 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 }) | - | |
| onValuesChange | Trigger when value updated | function(changedValues, allValues) | - | |
| clearOnDestroy | Clear form values when the form is uninstalled | boolean | false | 5.18.0 |
It accepts all props which native forms support but
onSubmit.
Form provides default verification error messages. You can modify the template by configuring validateMessages property. A common usage is to configure localization:
const validateMessages ={required:"'${name}' is required!",// ...};<FormvalidateMessages={validateMessages}/>;
Besides, ConfigProvider also provides a global configuration scheme that allows for uniform configuration error notification templates:
const validateMessages ={required:"'${name}' is Required!",// ...};<ConfigProviderform={{ validateMessages }}><Form/></ConfigProvider>;
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 | NamePath[] | - | |
| extra | The extra prompt message. It is similar to help. Usage example: to display error message and prompt message at the same time | ReactNode | - | |
| getValueFromEvent | Specify how to get value from event or other onChange arguments | (..args: any[]) => any | - | |
| getValueProps | Additional props with sub component (It's not recommended to generate dynamic function prop by getValueProps. Please pass it to child component directly) | (value: any) => Record<string, any> | - | 4.2.0 |
| hasFeedback | Used with validateStatus, this option specifies the validation status icon. Recommended to be used only with Input. Also, It can get feedback icons via icons prop. | boolean | { icons: FeedbackIcons } | false | icons: 5.9.0 |
| help | The prompt message. If not provided, the prompt message will be generated by the validation rule. | ReactNode | - | |
| hidden | Whether to hide Form.Item (still collect and validate value) | boolean | false | 4.4.0 |
| htmlFor | Set sub label htmlFor | string | - | |
| initialValue | Config sub default value. Form initialValues get higher priority when conflict | string | - | 4.2.0 |
| label | Label text. When there is no need for a label but it needs to be aligned with a colon, it can be set to null | ReactNode | - | null: 5.22.0 |
| labelAlign | The 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 <Col>. You can set labelCol on Form which will not affect nest Item. If both exists, use Item first | object | - | |
| messageVariables | The default validate field info, description see below | Record<string, string> | - | 4.7.0 |
| name | Field name, support array | NamePath | - | |
| normalize | Normalize value from component value before passing to Form instance. Do not support async | (value, prevValue, prevValues) => any | - | |
| noStyle | No style for true, used as a pure field control. Will inherit parent Form.Item validateStatus if self validateStatus not configured | boolean | false | |
| preserve | Keep field value even when field removed | boolean | true | 4.4.0 |
| required | Display required style. It will be generated by the validation rule | boolean | false | |
| rules | Rules for field validation. Click here to see an example | Rule[] | - | |
| shouldUpdate | Custom field update logic. See below | boolean | (prevValue, curValue) => boolean | false | |
| tooltip | Config tooltip info | ReactNode | TooltipProps & { icon: ReactNode } | - | 4.7.0 |
| trigger | When to collect the value of children node. Click here to see an example | string | onChange | |
| validateDebounce | Delay milliseconds to start validation | number | - | 5.9.0 |
| validateFirst | Whether stop validate on first rule of error for this field. Will parallel validate when parallel configured | boolean | parallel | false | parallel: 4.5.0 |
| 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 or Checkbox 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 which will not affect nest Item. If both exists, use Item first | object | - | |
| layout | Form item layout | horizontal | vertical | - | 5.18.0 |
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:
onChange on each form control to collect data(use onValuesChange of Form), but you can still listen to onChange.value or defaultValue prop, you should set default value with initialValues of Form. Note that initialValues cannot be updated by setState dynamically, you should use setFieldsValue in that situation.setState manually, please use form.setFieldsValue to change value programmatically.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.
dependencies shouldn't be used together with shouldUpdate, since it may result in conflicting update logic.
({ status: ValidateStatus, errors: ReactNode, warnings: ReactNode }) => Record<ValidateStatus, ReactNode>
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 property. In some specific cases, such as when a new field option appears with a field 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. It should be noted that the child component should be returned in a function, otherwise shouldUpdate won't behave correctly:
related issue: #34500
<Form.ItemshouldUpdate>{()=>{return<pre>{JSON.stringify(form.getFieldsValue(),null,2)}</pre>;}}</Form.Item>
You can ref example 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:
<Form.ItemshouldUpdate={(prevValues, curValues)=> prevValues.additional!== curValues.additional}>{()=>{return(<Form.Itemname="other"><Input/></Form.Item>);}}</Form.Item>
You can ref example to see detail.
You can modify the default verification information of Form.Item through messageVariables.
<Form><Form.ItemmessageVariables={{another:'good'}}label="user"rules={[{required:true,message:'${another} is required'}]}><Input/></Form.Item><Form.ItemmessageVariables={{label:'good'}}label={<span>user</span>}rules={[{required:true,message:'${label} is required'}]}><Input/></Form.Item></Form>
Since 5.20.2, when you don't want to convert ${}, you can use \\${} to skip:
{required:true,message:'${label} is convert, \\${label} is not convert'}// good is convert, ${label} is not convert
Provides array management for fields.
| Property | Description | Type | Default | Version |
|---|---|---|---|---|
| children | Render function | (fields: Field[], operation: { add, remove, move }, meta: { errors }) => React.ReactNode | - | |
| initialValue | Config sub default value. Form initialValues get higher priority when conflict | any[] | - | 4.9.0 |
| name | Field name, support array. List is also a field, so it will return all the values by getFieldsValue. You can change this logic by config | NamePath | - | |
| rules | Validate rules, only support customize validator. Should work with ErrorList | { validator, message }[] | - | 4.7.0 |
<Form.List>{(fields)=>(<div>{fields.map((field)=>(<Form.Item{...field}><Input/></Form.Item>))}</div>)}</Form.List>
Note: You should not configure Form.Item initialValue under Form.List. It always should be configured by Form.List initialValue or Form initialValues.
Some operator functions in render form of Form.List.
| Property | Description | Type | Default | Version |
|---|---|---|---|---|
| add | add form item | (defaultValue?: any, insertIndex?: number) => void | insertIndex | 4.6.0 |
| move | move form item | (from: number, to: number) => void | - | |
| remove | remove form item | (index: number | number[]) => void | number[] | 4.5.0 |
New in 4.7.0. Show error messages, should only work with rules of Form.List. See example.
| Property | Description | Type | Default |
|---|---|---|---|
| errors | Error list | ReactNode[] | - |
Provide linkage between forms. If a sub form with name prop update, it will auto trigger Provider related events. See example.
| 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 }) | - |
<Form.ProvideronFormFinish={(name)=>{if(name ==='form1'){// Do something...}}}><Formname="form1">...</Form><Formname="form2">...</Form></Form.Provider>
| Name | Description | Type | Version |
|---|---|---|---|
| getFieldError | Get the error messages by the field name | (name: NamePath) => string[] | |
| getFieldInstance | Get field instance | (name: NamePath) => any | 4.4.0 |
| getFieldsError | Get the error messages by the fields name. Return as an array | (nameList?: NamePath[]) => FieldError[] | |
| getFieldsValue | Get values by a set of field names. Return according to the corresponding structure. Default return mounted field value, but you can use getFieldsValue(true) to get all values | GetFieldsValue | |
| getFieldValue | Get the value by the field name | (name: NamePath) => any | |
| isFieldsTouched | Check if fields have been operated. Check if all fields is touched when allTouched is true | (nameList?: NamePath[], allTouched?: boolean) => boolean | |
| isFieldTouched | Check if a field has been operated | (name: NamePath) => boolean | |
| isFieldValidating | Check field if is in validating | (name: NamePath) => boolean | |
| resetFields | Reset fields to initialValues | (fields?: NamePath[]) => void | |
| scrollToField | Scroll to field position | (name: NamePath, options: ScrollOptions | { focus: boolean }) => void | focus: 5.24.0 |
| setFields | Set fields status | (fields: FieldData[]) => void | |
| setFieldValue | Set fields value(Will directly pass to form store and reset validation message. If you do not want to modify passed object, please clone first) | (name: NamePath, value: any) => void | 4.22.0 |
| setFieldsValue | Set fields value(Will directly pass to form store and reset validation message. If you do not want to modify passed object, please clone first). Use setFieldValue instead if you want to only config single value in Form.List | (values) => void | |
| submit | Submit the form. It's same as click submit button | () => void | |
| validateFields | Validate fields. Use recursive to validate all the field in the path | (nameList?: NamePath[], config?: ValidateConfig) => Promise |
exportinterfaceValidateConfig{// New in 5.5.0. Only validate content and not show error message on UI.validateOnly?:boolean;// New in 5.9.0. Recursively validate the provided `nameList` and its sub-paths.recursive?:boolean;// New in 5.11.0. Validate dirty fields (touched + validated).// It's useful to validate fields only when they are touched or validated.dirty?:boolean;}
return sample:
validateFields().then((values)=>{/*values:{username: 'username',password: 'password',}*/}).catch((errorInfo)=>{/*errorInfo:{values: {username: 'username',password: 'password',},errorFields: [{ name: ['password'], errors: ['Please input your Password!'] },],outOfDate: false,}*/});
type Form.useForm = (): [FormInstance]
Create Form instance to maintain data store.
type Form.useFormInstance = (): FormInstance
Added in 4.20.0. Get current context form instance to avoid pass as props between components:
constSub=()=>{const form =Form.useFormInstance();return<ButtononClick={()=> form.setFieldsValue({})}/>;};exportdefault()=>{const[form]=Form.useForm();return(<Formform={form}><Sub/></Form>);};
type Form.useWatch = (namePath: NamePath | (selector: (values: Store) => any), formInstance?: FormInstance | WatchOptions): Value
5.12.0 add selector
Watch the value of a field. You can use this to interact with other hooks like useSWR to reduce development costs:
constDemo=()=>{const[form]=Form.useForm();const userName =Form.useWatch('username', form);const{ data: options }=useSWR(`/api/user/${userName}`, fetcher);return(<Formform={form}><Form.Itemname="username"><AutoCompleteoptions={options}/></Form.Item></Form>);};
If your component is wrapped by Form.Item, you can omit the second argument, Form.useWatch will find the nearest FormInstance automatically.
By default useWatch only watches the registered field. If you want to watch the unregistered field, please use preserve:
constDemo=()=>{const[form]=Form.useForm();const age =Form.useWatch('age',{ form, preserve:true});console.log(age);return(<div><ButtononClick={()=> form.setFieldValue('age',2)}>Update</Button><Formform={form}><Form.Itemname="name"><Input/></Form.Item></Form></div>);};
type Form.Item.useStatus = (): { status: ValidateStatus | undefined, errors: ReactNode[], warnings: ReactNode[] }
Added in 4.22.0. Could be used to get validate status of Form.Item. If this hook is not used under Form.Item, status would be undefined. Added error and warnings in 5.4.0, Could be used to get error messages and warning messages of Form.Item:
constCustomInput=({ value, onChange })=>{const{ status, errors }=Form.Item.useStatus();return(<inputvalue={value}onChange={onChange}className={`custom-input-${status}`}placeholder={(errors.length&& errors[0])||''}/>);};exportdefault()=>(<Form><Form.Itemname="username"><CustomInput/></Form.Item></Form>);
Form only update the Field which changed to avoid full refresh perf issue. Thus you can not get real time value with getFieldsValue in render. And useWatch will rerender current component to sync with latest value. You can also use Field renderProps to get better performance if only want to do conditional render. If component no need care field value change, you can use onValuesChange to give to parent component to avoid current one rerender.
string | number | (string | number)[]
getFieldsValue provides overloaded methods:
When nameList is empty, return all registered fields, including values of List (even if List has no Item children).
When nameList is true, return all values in store, including unregistered fields. For example, if you set the value of an unregistered Item through setFieldsValue, you can also get all values through true.
When nameList is an array, return the value of the specified path. Note that nameList is a nested array. For example, you need the value of a certain path as follows:
// Single pathform.getFieldsValue([['user','age']]);// multiple pathform.getFieldsValue([['user','age'],['preset','account'],]);
To filter certain field values, meta will provide information related to the fields. For example, it can be used to retrieve values that have only been modified by the user, and so on.
typeFilterFunc=(meta:{ touched:boolean; validating:boolean})=>boolean;
| Name | Description | Type |
|---|---|---|
| errors | Error messages | string[] |
| warnings | Warning messages | string[] |
| name | Field name path | NamePath[] |
| touched | Whether is operated | boolean |
| validating | Whether is in validating | boolean |
| value | Field value | any |
Rule supports a config object, or a function returning config object:
typeRule=RuleConfig|((form:FormInstance)=>RuleConfig);
| Name | Description | Type | Version |
|---|---|---|---|
| defaultField | Validate rule for all array elements, valid when type is array | rule | |
| enum | Match enum value. You need to set type to enum to enable this | any[] | |
| fields | Validate rule for child elements, valid when type is array or object | Record<string, rule> | |
| len | Length of string, number, array | number | |
| max | type required: max length of string, number, array | number | |
| message | Error message. Will auto generate by template if not provided | string | ReactElement | |
| min | type required: 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 | string | |
| validateTrigger | Set validate trigger event. Must be the sub set of validateTrigger in Form.Item | string | string[] | |
| validator | Customize validation rule. Accept Promise as return. See example | (rule, value) => Promise | |
| warningOnly | Warning only. Not block form submit | boolean | 4.17.0 |
| whitespace | Failed if only has whitespace, only work with type: 'string' rule | boolean |
| Name | Description | Type | Default | Version |
|---|---|---|---|---|
| form | Form instance | FormInstance | Current form in context | 5.4.0 |
| preserve | Whether to watch the field which has no matched Form.Item | boolean | false | 5.4.0 |
| Token Name | Description | Type | Default Value |
|---|---|---|---|
| inlineItemMarginBottom | Inline layout form item margin bottom | number | 0 |
| itemMarginBottom | Form item margin bottom | number | 24 |
| labelColonMarginInlineEnd | Label colon margin-inline-end | number | 8 |
| labelColonMarginInlineStart | Label colon margin-inline-start | number | 2 |
| labelColor | Label color | string | rgba(0,0,0,0.88) |
| labelFontSize | Label font size | number | 14 |
| labelHeight | Label height | string | number | 32 |
| labelRequiredMarkColor | Required mark color | string | #ff4d4f |
| verticalLabelMargin | Vertical layout label margin | Margin<string | number> | undefined | 0 |
| verticalLabelPadding | Vertical layout label padding | Padding<string | number> | undefined | 0 0 8px |
Form.Item default bind value to value prop, but Switch or Checkbox value prop is checked. You can use valuePropName to change bind value prop.
<Form.Itemname="fieldA"valuePropName="checked"><Switch/></Form.Item>
name fill value when it's an array?name will fill value by array order. When there exists number in it and no related field in form store, it will auto convert field to array. If you want to keep it as object, use string like: ['1', 'name'].
Warning: Instance created by
useFormis not connect to any Form element. Forget to passformprop?
Before Modal opens, children elements do not exist in the view. You can set forceRender on Modal to pre-render its children. Click here to view an example.
defaultValue not working when inside Form.Item?Components inside Form.Item with name property will turn into controlled mode, which makes defaultValue not work anymore. Please try initialValues of Form to set default value.
ref of Form at first time?ref only receives the mounted instance. please ref React official doc: https://react.dev/learn/manipulating-the-dom-with-refs#when-react-attaches-the-refs
resetFields re-mount component?resetFields will re-mount component under Field to clean up customize component side effects (like async data, cached state, etc.). It's by design.
In most case, we always recommend to use Form initialValues. Use Item initialValue only with dynamic field usage. Priority follows the rules:
initialValues is the first priorityinitialValue is secondary *. Does not work when multiple Item with same name setting the initialValuegetFieldsValue get value at first render?getFieldsValue returns collected field data by default, but the Form.Item node is not ready at the first render. You can get all field data by getFieldsValue(true).
setFieldsValue to undefined?value change from certain one to undefined in React means from controlled mode to uncontrolled mode. Thus it will not change display value but modified FormStore in fact. You can HOC to handle this:
constMyInput=({// Force use controlled modevalue ='',...rest})=><inputvalue={value}{...rest}/>;<Form.Itemname="my"><MyInput/></Form.Item>;
onFieldsChange trigger three times on change when field sets rules?Validating is also part of the value updating. It pass follow steps:
In each onFieldsChange, you will get false > true > false with isFieldValidating.
label and need ErrorList to show errors?Form.List use renderProps which mean internal structure is flexible. Thus label and error can not have best place. If you want to use antd label, you can wrap with Form.Item instead.
dependencies work on Form.List field?Your name path should also contain Form.List name:
<Form.Listname="users">{(fields)=>fields.map((field)=>(<React.Fragmentkey={field.key}><Form.Itemname={[field.name,'name']}{...someRest1}/><Form.Itemname={[field.name,'age']}{...someRest1}/></React.Fragment>))}</Form.List>
dependencies should be ['users', 0, 'name']
normalize support async?React can not get correct interaction of controlled component with async value update. When user trigger onChange, component will do no response since value update is async. If you want to trigger value update async, you should use customize component to handle value state internal and pass sync value control to Form instead.
scrollToFirstError and scrollToField not working?See similar issues: #28370 #27994
Starting from version 5.17.0, the sliding operation will prioritize using the ref element forwarded by the form control elements. Therefore, when considering custom components to support verification scrolling, please consider forwarding it to the form control elements first.
scrollToFirstError and scrollToField deps on id attribute passed to form control, please make sure that it hasn't been ignored in your custom form control. Check codesandbox for solution.
If there are multiple forms on the page, and there are duplicate same name form item, the form scroll probably may find the form item with the same name in another form. You need to set a different name for the Form component to distinguish it.
ref to bind element?Form can not get real DOM node when customize component not support ref. It will get warning in React Strict Mode if wrap with Class Component and call findDOMNode. So we use id to locate element.
setFieldsValue do not trigger onFieldsChange or onValuesChange?It's by design. Only user interactive can trigger the change event. This design is aim to avoid call setFieldsValue in change event which may makes loop calling.
Form.Item will inject value and onChange to children when render. Once your field component is wrapped, props will not pass to the correct node. Follow code will not work as expect:
<Form.Itemname="input"><div><h3>I am a wrapped Input</h3><Input/></div></Form.Item>
You can use HOC to solve this problem, don't forget passing props to form control component:
constMyInput=(props)=>(<div><h3>I am a wrapped Input</h3><Input{...props}/></div>);<Form.Itemname="input"><MyInput/></Form.Item>;
Form label use HTML label elements to wrap form controls, which focuses the corresponding control when clicked. This is the native behavior of label elements, designed to improve accessibility and user experience. This standard interaction pattern makes it easier for users to interact with form controls. If you need to disable this behavior, you can use htmlFor={null}, though it's generally not recommended.
- <Form.Item name="switch" label="Switch">+ <Form.Item name="switch" label="Switch" htmlFor={null}><Switch /></Form.Item>
When validation fails or manually scroll to the error field.
Basic Form data control. Includes layout, initial values, validation and submit.
Call form method with Form.useForm.
Note that
useFormis a React Hooks that only works in functional component. You can also userefto get the form instance in class component: https://codesandbox.io/p/sandbox-ngtjtm
There are three layout for form: horizontal, vertical, inline.
Defining a separate layout on Form.Item can achieve multiple layouts for a single form.
Set component to disabled, only works for antd components.
Change the variant of all components in the form, options include: outlined filled borderless and underlined.
Switch required or optional style with requiredMark.
Set component size, only works for antd components.
Turn on labelWrap to wrap label if text is long.
rule with warningOnly will not block form submit.
useWatch helps watch the field change and only re-render for the value change. API Ref.
For the async validation scenario, high frequency of verification will cause backend pressure. You can change the verification timing through validateTrigger, or change the verification frequency through validateDebounce, or set the verification short circuit through validateFirst.
Dynamic adjust submit button's disabled status by validateOnly of validateFields.
In some scenarios, you may want to set a prefix for some fields consistently. You can achieve this effect with HOC.
Add or remove form items dynamically. add function support config initial value.
Nest dynamic field need extends field. Pass field.name to nest item.
Multiple Form.List nested usage scenarios.
name prop support nest data structure. Customize validate message template with validateMessages or message. Ref here about message template.
This demo shows how to use Form.Item with multiple controls. <Form.Item name="field" /> will only bind the control(Input/Select) which is the only children of it. Imagine this case: you added some text description after the Input, then you have to wrap the Input by an extra <Form.Item name="field">. style property of Form.Item could be useful to modify the nested form item layout, or use <Form.Item noStyle /> to turn it into a pure form-binded component(like getFieldDecorator in 3.x).
- <Form.Item label="Field" name="field">
- <Input />
- </Form.Item>
+ <Form.Item label="Field">
+ <Form.Item name="field" noStyle><Input /></Form.Item> // that will bind input
+ <span>description</span>
+ </Form.Item>
This demo shows three typical usages:
Username: extra elements after control, using <Form.Item name="field" noStyle /> inside Form.Item to bind Input.Address: two controls in one line, using two <Form.Item name="field" noStyle /> to bind each control.BirthDate:two controls in one line with independent error message, using two <Form.Item name="field" noStyle /> to bind each control, make layout inline by customizing style property.Note that, in this case, no more
nameproperty should be left in Form.Item with label.
See the Customized Form Controls demo below for more advanced usage.
Customized or third-party form controls can be used in Form, too. Controls must follow these conventions:
- It has a controlled property
valueor other name which is equal to the value ofvaluePropName.- It has event
onChangeor an event which name is equal to the value oftrigger.- Forward the ref or pass the id property to dom to support the
scrollToFieldmethod.
We can store form data into upper component or Redux or dva by using onFieldsChange and fields, see more at this rc-field-form demo.
Note: Save Form data globally is not a good practice. You should avoid this if not necessary.
Use Form.Provider to process data between forms. In this case, submit button is in the Modal which is out of Form. You can use form.submit to submit form. Besides, we recommend native <Button htmlType="submit" /> to submit a form.
Inline login form is often used in navigation bar.
Normal login form which can contain more elements.
Fill in this form to create a new account for you.
Three columns layout is often used for advanced searching of data table.
Because the width of label is not fixed, you may need to adjust it by customizing its style.
When user visit a page with a list of items, and want to create a new item. The page can popup a form in Modal, then let user fill in the form to create an item.
Form will collect and validate form data automatically. But if you don't need this feature or the default behavior cannot satisfy your business, you can handle form data manually.
We provide properties like validateStatus help hasFeedback to customize your own validate status and message, without using Form.
validateStatus: validate status of form components which could be 'success', 'warning', 'error', 'validating'.hasFeedback: display feed icon of input controlhelp: display validate message.Perform different check rules according to different situations.
Form.Item can set the associated field through the dependencies property. When the value of the associated field changes, the validation and update will be triggered.
By combining getValueProps and normalize, it is possible to convert the format of value, such as converting the timestamp into a dayjs object and then passing it to the DatePicker.
Demonstration of validation configuration for form controls which are not shown in the demos above.
You can customize the semantic dom style of Form by passing objects/functions through classNames and styles.
Name Value:
Custom Value: name:
[
{
"name": [
"username"
],
"value": "Ant Design"
}
]