Form

High-performance form controls with built-in data field management. Including data entry, verification and corresponding styles.

Install

npm install antd-mobile@5.43.0

antd-mobile is for mobile web, not React Native or Mini Programs. React 19 projects must register createRoot with unstableSetRender at the entry, or imperative APIs such as Toast and Dialog cannot render. Switch dark mode with <html data-prefers-color-scheme="dark">.

Examples come from the official Ant Design Mobile repository (MIT) at the commit published as npm 5.43.0. Presentation helpers such as DemoBlock are JGuang rewrites, not antd-mobile APIs.

High-performance form controls with built-in data field management. Including data entry, verification and corresponding styles.

When to Use

• Suitable for creating an entity or collecting information.
• When the input data type needs to be checked.

Demos

Validate Only

You can use validateOnly of validateFields to validate the form without showing error UI. This is commonly used to dynamically control the disabled state of the submit button.

getvalueprops-normalize

Form

Props

FormInstance

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} />;

CSS Variables

Form.Item

Props

The layout of Form.Item is based on List.Item. So it also supports these props of List.Item:

extra clickable arrow description

A control wrapped by Form.Item with the name property set, the form control will automatically add value (or other properties specified by valuePropName) onChange (or other properties specified by trigger), data synchronization will be taken over by Form. So if you set a name property on Form.Item, make sure its children is a valid ReactElement control and can accept the value' mentioned above and onChange properties (or other properties specified), for example:

<Form.Item name='foo'>
  <Input />
</Form.Item>

And the following spellings are wrong:

<Form.Item name='foo'>
  <Input />
  <div>hello</div>
</Form.Item>
// Wrong: Form.Item's children contain multiple elements

<Form.Item name='foo'>
  hello
  <Input />
</Form.Item>
// Wrong: Same as above, Form.Item's children contains multiple elements

<Form.Item name='foo'>
  <div>
    <Input />
  </div>
</Form.Item>
// Wrong: Form.Item's children is actually a div, and div cannot accept value and onChange properties

Also, please note:

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.

For example, the following code is wrong:

<Form.Item name='foo'>
  <Input
    value={myInputValue} // Wrong: Value should not be manually controlled
    onChange={(v) => { setMyInputValue(v) }} // Wrong: Although you can listen to the onChange event, you should not maintain your own state here
  />
</Form.Item>

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

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

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:

<Form.Item shouldUpdate>
  {() => {
    return <pre>{JSON.stringify(form.getFieldsValue(), null, 2)}</pre>;
  }}
</Form.Item>

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>

messageVariables

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

<Form>
  <Form.Item messageVariables={{ another: 'good' }} label="user">
    <Input />
  </Form.Item>
  <Form.Item messageVariables={{ label: 'good' }} label={<span>user</span>}>
    <Input />
  </Form.Item>
</Form>

Custom field

Customized or third-party form controls can be used in Form, too. Controls must follow these conventions:

• It has a controlled property value.
• It has event onChange.

Form.Header

You can use Form.Header to group form items.

Props

Form.Subscribe

Props

useWatch

Demo

Form.Array <Experimental></Experimental>

Provides array management for fields.

FormArrayField

FormArrayOperation

The operation functions for Form.Array.

Demo

Some Common Type Definitions

NamePath

string | number | (string | number)[]

ValidateOptions

FieldData

Rule

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

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

FAQ

How does Form.Item work with Picker / DatePicker / CascadePicker?

First, we can render the currently selected value through the children rendering function of Picker. Here we have taken DatePicker as an example, but the same is true for the other two Pickers:

<DatePicker>
  {value =>
    value ? dayjs(value).format('YYYY-MM-DD') : 'Please select'
  }
</DatePicker>

Next we need to deal with the show/hide state of the Picker, which is where the Picker component is the most different and confusing from other form components. If we put the Picker directly in the Form.Item, there is no way to show it to the user, no matter how clicked, it will not let Picker pops up:

<Form.Item
  name='birthday'
  label='Birthday'
>
  <DatePicker>
    {value =>
      value ? dayjs(value).format('YYYY-MM-DD') : 'Please select'
    }
  </DatePicker>
</Form.Item>

In most cases, the effect we need to achieve is that clicking on the outer Form.Item will trigger the display of the inner Picker. However, on Form.Item, how can I control the Picker? Maybe you'll want to declare a state yourself to control manually, for example:

const [visible, setVisible] = useState(false)

<Form.Item
  name='birthday'
  label='Birthday'
  onClick={() => {
    setVisible(true)
  }}
>
  <DatePicker
    visible={visible}
    onClose={() => {
      setVisible(false)
    }}
  >
    {value =>
      value ? dayjs(value).format('YYYY-MM-DD') : 'Please select'
    }
  </DatePicker>
</Form.Item>

But this is too cumbersome to write, and if there are multiple Pickers in a form or it is used with Form.Array, it will crash.

So antd-mobile provides a convenient method, you can directly get the ref of the internal children in the onClick event of Form.Item, so we can write:

<Form.Item
  name='birthday'
  label='Birthday'
  onClick={(e, datePickerRef: RefObject<DatePickerRef>) => {
    datePickerRef.current?.open() // ⬅️
  }}
>
  <DatePicker>
    {value =>
      value ? dayjs(value).format('YYYY-MM-DD') : 'Please select'
    }
  </DatePicker>
</Form.Item>

Finally, don't forget that the Picker component's confirmation event is onConfirm not onChange, so you need to configure trigger:

<Form.Item
  name='birthday'
  label='Birthday'
  trigger='onConfirm'  // ⬅️
  onClick={(e, datePickerRef: RefObject<DatePickerRef>) => {
    datePickerRef.current?.open()
  }}
>
  ...
</Form.Item>