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 data control. Includes layout, initial values, validation and submit.

Form methods

Call form method with Form.useForm. > Note that useForm is a React Hooks that only works in functional component. You can also use ref to get the form instance in class component: https://codesandbox.io/p/sandbox-ngtjtm

Form Layout

There are three layout for form: horizontal, vertical, inline.

Form mix layout

Defining a separate layout on Form.Item can achieve multiple layouts for a single form.

Form disabled

Set component to disabled, only works for library components.

Form variants

Change the variant of all components in the form, options include: outlined filled borderless and underlined.

Required style

Switch required or optional style with requiredMark.

Form size

Set component size, only works for library components.

label can wrap

Turn on labelWrap to wrap label if text is long.

No block rule

rule with warningOnly will not block form submit.

Watch Hooks

useWatch helps watch the field change and only re-render for the value change. API Ref.

Validate Trigger

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.

Validate Only

Dynamic adjust submit button's disabled status by validateOnly of validateFields.

Path Prefix

In some scenarios, you may want to set a prefix for some fields consistently. You can achieve this effect with HOC.

Dynamic Form Item

Add or remove form items dynamically. add function support config initial value.

Dynamic Form nest Items

Nest dynamic field need extends field. Pass field.name to nest item.

Drag sorting

Combine dnd-kit with the move operation provided by Form.List to drag and sort dynamic form items. Each field's stable key is used as the drag identifier, and move(from, to) is called on drag end to reorder items while keeping the form values in sync.

Complex Dynamic Form Item

Multiple Form.List nested usage scenarios.

Nest

name prop support nest data structure. Customize validate message template with validateMessages or message. Ref here about message template.

complex form control

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). diff - <Form.Item label="Field" name="field"> - <Input /> - </Form.Item> + <Form.Item label="Field" htmlFor="field"> + <Form.Item name="field" noStyle><Input id="field" /></Form.Item> + {/* The nested item binds the input. */} + <span>description</span> + </Form.Item> When the outer labeled Form.Item has no name, it cannot infer the nested control's ID. If the label describes a single control, set htmlFor on the outer item and the same id on the nested control to preserve label-click focus and screen reader association. 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 name property should be left in Form.Item with label. See the Customized Form Controls demo below for more advanced usage.

Customized Form Controls

Customized or third-party form controls can be used in Form, too. Controls must follow these conventions: > - It has a controlled property value or other name which is equal to the value of valuePropName. > - It has event onChange or an event which name is equal to the value of trigger. > - Forward the ref or pass the id property to dom to support the scrollToField method.

Store Form Data into Upper Component

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. onFieldsChange returns a flat FieldData[]. When a field uses an array name path, FieldData.name keeps that path instead of converting it into a nested object, making it easier to process each field entry in the external state. **Note:** Saving form data globally is not a good practice. You should avoid this if not necessary.

Control between forms

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

Inline login form is often used in navigation bar.

Login Form

Normal login form which can contain more elements.

Registration

Fill in this form to create a new account for you.

Advanced search

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.

Form in Modal to Create

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.

Time-related Controls

The value of time-related components is a dayjs object, which we need to pre-process it before we submit to server.

Handle Form Data Manually

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.

Customized Validation

We provide properties like validateStatus help hasFeedback to customize your own validate status and message, without using Form. 1. validateStatus: validate status of form components which could be 'success', 'warning', 'error', 'validating'. 2. hasFeedback: display feed icon of input control 3. help: display validate message.

Dynamic Rules

Perform different check rules according to different situations.

Dependencies

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.

getValueProps + normalize

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.

Slide to error field

When validation fails or manually scroll to the error field.

Other Form Controls

Demonstration of validation configuration for form controls which are not shown in the demos above.

Custom semantic dom styling

You can customize the semantic dom style of Form by passing objects/functions through classNames and styles.

API

Form, Form.Item, Form.List, and Form.Provider are exported from @ceebee/ui/client.

Form

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 \| medium \| large`	`-`	—
`styles`	Customize inline style for each semantic structure inside the component. Supports object or function.	`Record<SemanticDOM, CSSProperties> \| (info: { props })=> Record<SemanticDOM, CSSProperties>`	`-`	—
`tooltip`	Config tooltip props	`TooltipProps & { icon?: ReactNode }`	`-`	6.3.0
`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 unmounted	`boolean`	`false`	5.18.0

validateMessages

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 alignment of the 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. When not set, it will be generated by the validation rule. Set it to false to disable the style.	`boolean`	`-`	—
`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 content	`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

messageVariables

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
`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
`errors`	Error list	`ReactNode\[]`	`-`	—
`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 })`	`-`	—

FormInstance

Property	Description	Type	Default	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`	`—`	—

FieldData

Property	Description	Type	Default	Version
`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

Property	Description	Type	Default	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 \| tel. 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`	`—`	—

WatchOptions

Property	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