Form

High-performance form component with data domain management. Includes data entry, validation, and corresponding styles.

When to use

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

Examples

• Basic Usage · basic

• Form methods · control-hooks

• Form Layout · layout

• Form mix layout · layout-multiple

• Form disabled · disabled

• Form variants · variant

• Required style · required-mark

• Form size · size

• label can wrap · layout-can-wrap

• No block rule · warning-only

• Watch Hooks · useWatch

• Validate Trigger · validate-trigger

• Validate Only · validate-only

• Path Prefix · form-item-path

• Dynamic Form Item · dynamic-form-item

• Dynamic Form nest Items · dynamic-form-items

• Drag sorting · dynamic-form-items-drag-sorting

• Complex Dynamic Form Item · dynamic-form-items-complex

• Nest · nest-messages

• complex form control · complex-form-control

• Customized Form Controls · customized-form-controls

• Store Form Data into Upper Component · global-state

• Control between forms · form-context

• Inline Login Form · inline-login

• Login Form · login

• Registration · register

• Advanced search · advanced-search

• Form in Modal to Create · form-in-modal

• Time-related Controls · time-related-controls

• Handle Form Data Manually · without-form-create

• Customized Validation · validate-static

• Dynamic Rules · dynamic-rule

• Dependencies · form-dependencies

• getValueProps + normalize · getValueProps-normalize

• Slide to error field · validate-scroll-to-field

• Other Form Controls · validate-other

• Custom semantic dom styling · style-class

API

Common props ref：Common props

Form

It accepts all props which native forms support but onSubmit.

validateMessages

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!",
  // ...
};

<Form validateMessages={validateMessages} />;

Besides, ConfigProvider also provides a global configuration scheme that allows for uniform configuration error notification templates:

const validateMessages = {
  required: "'${name}' is Required!",
  // ...
};

<ConfigProvider form={{ validateMessages }}>
  <Form />
</ConfigProvider>;

Form.Item

Form field component for data bidirectional binding, validation, layout, and so on.

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 dynamically, 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.

dependencies shouldn't be used together with shouldUpdate, since it may result in conflicting update logic.

FeedbackIcons

({ status: ValidateStatus, errors: ReactNode, warnings: ReactNode }) => Record<ValidateStatus, ReactNode>

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 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.Item shouldUpdate>
  {() => {
    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.Item shouldUpdate={(prevValues, curValues) => prevValues.additional !== curValues.additional}>
  {() => {
    return (
      <Form.Item name="other">
        <Input />
      </Form.Item>
    );
  }}
</Form.Item>

You can ref example to see detail.

messageVariables

You can modify the default verification information of Form.Item through messageVariables.

<Form>
  <Form.Item
    messageVariables={{ another: 'good' }}
    label="user"
    rules={[{ required: true, message: '${another} is required' }]}
  >
    <Input />
  </Form.Item>
  <Form.Item
    messageVariables={{ 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

Form.List

Provides array management for fields.

<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.

operation

Some operator functions in render form of Form.List.

Form.ErrorList

New in 4.7.0. Show error messages, should only work with rules of Form.List. See example.

Form.Provider

Provide linkage between forms. If a sub form with name prop update, it will auto trigger Provider related events. See example.

<Form.Provider
  onFormFinish={(name) => {
    if (name === 'form1') {
      // Do something...
    }
  }}
>
  <Form name="form1">...</Form>
  <Form name="form2">...</Form>
</Form.Provider>

FormInstance

validateFields

export interface ValidateConfig {
  // 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,
      }
    */
  });

Hooks

Form.useForm

type Form.useForm = (): [FormInstance]

Create Form instance to maintain data store.

Form.useFormInstance

type Form.useFormInstance = (): FormInstance

Added in 4.20.0. Get current context form instance to avoid pass as props between components:

const Sub = () => {
  const form = Form.useFormInstance();

  return <Button onClick={() => form.setFieldsValue({})} />;
};

export default () => {
  const [form] = Form.useForm();

  return (
    <Form form={form}>
      <Sub />
    </Form>
  );
};

Form.useWatch

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:

const Demo = () => {
  const [form] = Form.useForm();
  const userName = Form.useWatch('username', form);

  const { data: options } = useSWR(`/api/user/${userName}`, fetcher);

  return (
    <Form form={form}>
      <Form.Item name="username">
        <AutoComplete options={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:

const Demo = () => {
  const [form] = Form.useForm();

  const age = Form.useWatch('age', { form, preserve: true });
  console.log(age);

  return (
    <div>
      <Button onClick={() => form.setFieldValue('age', 2)}>Update</Button>
      <Form form={form}>
        <Form.Item name="name">
          <Input />
        </Form.Item>
      </Form>
    </div>
  );
};

Form.Item.useStatus

type Form.Item.useStatus = (): { status: ValidateStatus | undefined, errors: ReactNode[], warnings: ReactNode[] }

The Form.Item.useStatus hook returns the validation status of a Form.Item and was added in 4.22.0. When used outside Form.Item, it returns undefined for the status field. The errors and warnings fields were added in 5.4.0 to obtain error and warning messages of Form.Item:

const CustomInput = ({ value, onChange }) => {
  const { status, errors } = Form.Item.useStatus();
  return (
    <input
      value={value}
      onChange={onChange}
      className={`custom-input-${status}`}
      placeholder={(errors.length && errors[0]) || ''}
    />
  );
};

export default () => (
  <Form>
    <Form.Item name="username">
      <CustomInput />
    </Form.Item>
  </Form>
);

Difference from other data fetching methods

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.

Interface

NamePath

string | number | (string | number)[]

GetFieldsValue

getFieldsValue provides overloaded methods:

getFieldsValue(nameList?: true | NamePath[], filterFunc?: FilterFunc)

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 path
form.getFieldsValue([['user', 'age']]);

// multiple path
form.getFieldsValue([
  ['user', 'age'],
  ['preset', 'account'],
]);

getFieldsValue({ filter?: FilterFunc })

FilterFunc

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.

type FilterFunc = (meta: { touched: boolean; validating: boolean }) => boolean;

FieldData

Rule

Rule supports a config object, or a function returning config object:

type Rule = RuleConfig | ((form: FormInstance) => RuleConfig);

WatchOptions

Semantic DOM

Semantic description source: vendor/components/form/demo/_semantic.tsx

Design Token

Types, inheritance and declarations retain the pinned native source. Defaults are computed by the native theme and may be overridden by ConfigProvider; this table does not invent static defaults.

Declaration source: vendor/components/form/style/index.ts

import type { CSSProperties } from 'react';

import type { CSSObject } from '@ant-design/cssinjs';

import { unit } from '@ant-design/cssinjs';

import { resetComponent } from '../../style';

import { genCollapseMotion, zoomIn } from '../../style/motion';

import type {
  AliasToken,
  FullToken,
  GenerateStyle,
  GenStyleFn,
  GetDefaultToken,
} from '../../theme/internal';

import { genStyleHooks, mergeToken } from '../../theme/internal';

import { genCssVar } from '../../theme/util/genStyleUtils';

import genFormValidateMotionStyle from './explain';

export interface ComponentToken {
  /**
   * @desc 必填项标记颜色
   * @descEN Required mark color
   */
  labelRequiredMarkColor: string;
  /**
   * @desc 标签颜色
   * @descEN Label color
   */
  labelColor: string;
  /**
   * @desc 标签字体大小
   * @descEN Label font size
   */
  labelFontSize: number;
  /**
   * @desc 标签高度
   * @descEN Label height
   */
  labelHeight: number | string;
  /** @internal */
  verticalLabelHeight: number | string;
  /**
   * @desc 标签冒号前间距
   * @descEN Label colon margin-inline-start
   */
  labelColonMarginInlineStart: number;
  /**
   * @desc 标签冒号后间距
   * @descEN Label colon margin-inline-end
   */
  labelColonMarginInlineEnd: number;
  /**
   * @desc 表单项间距
   * @descEN Form item margin bottom
   */
  itemMarginBottom: number;
  /**
   * @desc 行内布局表单项间距
   * @descEN Inline layout form item margin bottom
   */
  inlineItemMarginBottom: number;
  /**
   * @desc 垂直布局标签内边距
   * @descEN Vertical layout label padding
   */
  verticalLabelPadding: CSSProperties['padding'];
  /**
   * @desc 垂直布局标签外边距
   * @descEN Vertical layout label margin
   */
  verticalLabelMargin: CSSProperties['margin'];
}

/**
 * @desc Form 组件的 Token
 * @descEN Token for Form component
 */
export interface FormToken extends FullToken<'Form'> {
  /**
   * @desc 表单项类名
   * @descEN Form item class name
   */
  formItemCls: string;
  /**
   * @desc 根前缀类名
   * @descEN Root prefix class name
   */
  rootPrefixCls: string;
}

FAQ

Why can't Segmented be disabled by Form disabled?

Segmented is designed as a data display component, not a form control component. Although it can be used as a form control similar to Radio, it was not designed for this purpose. Therefore, its behavior is more similar to the Tabs component and will not be disabled by Form's disabled prop. For related discussions, see #54749.

Why can't Switch, Checkbox bind data?

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.Item name="fieldA" valuePropName="checked">
  <Switch />
</Form.Item>

How does 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'].

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 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.

Why is component 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.

Why can not call 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

Why will 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.

Difference between Form initialValues and Item initialValue?

In most case, we always recommend to use Form initialValues. Use Item initialValue only with dynamic field usage. Priority follows the rules:

1. Form initialValues is the first priority
2. Field initialValue is secondary *. Does not work when multiple Item with same name setting the initialValue

Why can't getFieldsValue 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).

Why do some components not respond to setFieldsValue with 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:

const MyInput = ({
  // Force use controlled mode
  value = '',
  ...rest
}) => <input value={value} {...rest} />;

<Form.Item name="my">
  <MyInput />
</Form.Item>;

Why does onFieldsChange trigger three times on change when field sets rules?

Validating is also part of the value updating. It passes through the following steps:

1. Trigger value change
2. Rule validating
3. Rule validated

In each onFieldsChange, you will get false > true > false with isFieldValidating.

Why doesn't Form.List support 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.

Why can't Form.Item dependencies work on Form.List field?

Your name path should also contain Form.List name:

<Form.List name="users">
  {(fields) =>
    fields.map((field) => (
      <React.Fragment key={field.key}>
        <Form.Item name={[field.name, 'name']} {...someRest1} />
        <Form.Item name={[field.name, 'age']} {...someRest1} />
      </React.Fragment>
    ))
  }
</Form.List>

dependencies should be ['users', 0, 'name']

Why doesn't normalize support async?

React cannot get correct interaction of controlled components with async value updates. When a user triggers onChange, the component will not respond since the value update is async. If you want to trigger value updates asynchronously, you should use a custom component to handle the value state internally and pass synchronous value control to the Form instead.

scrollToFirstError and scrollToField not working?

1. use custom form control

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 depend on the id attribute passed to form controls. Make sure that it hasn't been ignored in your custom form control. Check codesandbox for a solution.

2. multiple forms on same page

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.

Continue, why not use 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 interaction can trigger the change event. This design aims to avoid calling setFieldsValue in change events, which may cause infinite loops.

Why can't dependencies respond to setFieldsValue updates?

dependencies is mainly used for validation linkage between fields. When an upstream field is updated by user interaction, the dependent field will be updated and validated again. If you need to render additional content or switch field options based on values updated by setFieldsValue, use shouldUpdate or useWatch instead.

Why Form.Item not update value when children is nest?

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.Item name="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:

const MyInput = (props) => (
  <div>
    <h3>I am a wrapped Input</h3>
    <Input {...props} />
  </div>
);

<Form.Item name="input">
  <MyInput />
</Form.Item>;

Why does clicking the label in the form change the component state?

Related issue: #47031, #43175, #52152

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>

Is there more reference documentation?

• You can read 《antd v4 Form Best Practices》 for some usage tips and suggestions (Chinese).
• Want to use before and after in DatePicker and Switch? You can refer to 《How to elegantly add before and after to Form.Item children》 (Chinese).
• Elegant Form + Modal combination solution 《How to elegantly use Form + Modal》 (Chinese).

Shared native props

Tips: The following generic properties apply to most antd components; those not supported are described separately.

Install and reproduce an example

npm install antd@6.6.5 @ant-design/icons@6.3.4 dayjs@1.11.23

Use ConfigProvider and native App; configure dayjs locale separately. Each example lists its complete source files and additional pinned dependencies in View code. Example names select demos, not universal component props. See the resource setup guide for theme, locale and SSR.

Native type references

The source viewer includes unchanged native implementations and the following source declarations. Inherited types remain in their native packages. English source comments are preserved as code reference.

• vendor/components/form/ErrorList.tsx
• vendor/components/form/Form.tsx
• vendor/components/form/FormItem/ItemHolder.tsx
• vendor/components/form/FormItem/StatusProvider.tsx
• vendor/components/form/FormItem/index.tsx
• vendor/components/form/FormItemInput.tsx
• vendor/components/form/FormItemLabel.tsx
• vendor/components/form/FormList.tsx
• vendor/components/form/context.tsx
• vendor/components/form/hooks/useForm.ts
• vendor/components/form/hooks/useFormItemStatus.ts
• vendor/components/form/hooks/useFrameState.ts
• vendor/components/form/hooks/useVariants.ts
• vendor/components/form/index.tsx
• vendor/components/form/interface.ts
• vendor/components/form/style/index.ts

Source and license

https://github.com/ant-design/ant-design/tree/4a39f54842eade4e565ab336ef6097cd7e723cdd

Original bilingual prose and executable examples are retained. Website-only embeds and token tables are expanded locally. Ant Design is MIT; separately listed dependency notices also apply. Upload previews block outbound requests and do not provide a backend.