React Performance First Form Component

Common errors

• Error: Invalid hook call. Hooks can only be called inside of the body of a function component.

  cause The `useForm` hook was called outside of a React functional component, within a loop, a conditional statement, or a regular JavaScript function.
  fix Relocate the `useForm()` call to the top level of your functional component or custom hook to comply with React's Rules of Hooks.

• TypeError: Cannot read properties of undefined (reading 'Provider')

  cause This usually indicates an issue with the React context setup, often when `rc-field-form`'s components are rendered in an invalid React tree or if `react` / `react-dom` peer dependencies are not met.
  fix Verify that your `react` and `react-dom` versions satisfy the peer dependency requirements (`>=16.9.0`). Ensure that `Form` and `Field` components are imported correctly and rendered within a valid React functional component.

• Validation failed: Please input your username!

  cause A `Field` component's `rules` prop with `required: true` is failing validation, possibly on initial render or due to an empty input.
  fix Review the `rules` prop on your `Field` components. If `initialValues` are being used, ensure they satisfy any `required` constraints. Adjust `validateTrigger` if validation should only occur on specific events (e.g., 'onBlur', 'onSubmit').

• TypeError: Cannot destructure property 'someField' of 'values' as it is undefined.

  cause The `name` prop of a `Field` component is incorrect, missing, or the corresponding field is not present in the form's current values object when `onFinish` or `onValuesChange` is triggered.
  fix Double-check that the `name` prop on all `Field` components precisely matches the keys you expect in your form's value object. Provide `initialValues` to ensure all fields have a default presence in the form state.

• Argument of type '{ name: string; }' is not assignable to parameter of type 'FieldData'.

  cause This TypeScript error often occurs when incorrectly typing objects passed to `FormInstance` methods like `setFields` or when interacting with `Field` props without respecting the defined types.
  fix Use the provided TypeScript types, such as `FormInstance` and `FieldData`, correctly. When calling form methods or passing props, ensure the object structure aligns with the library's type definitions. Utilize generic types for `useForm<T>` where `T` is your form's value interface.

Warnings

• breaking There is significant confusion regarding the package name and versioning. The npm package is `rc-field-form` at version `2.7.1`, but recent release notes provided specifically refer to `@rc-component/form` (e.g., v1.8.1). This indicates a potential package rename, a shift to a monorepo structure where `@rc-component/form` is the primary active development, or that `rc-field-form` might be considered legacy or a wrapper. Developers should verify the official GitHub repository for the most current and actively maintained package name and usage instructions to avoid using an unmaintained version.
  Fix: Consult the official GitHub repository (react-component/field-form) for clarity on whether `rc-field-form` or `@rc-component/form` is the intended package for new projects and active development. Plan for potential migration if `rc-field-form` is deprecated in favor of `@rc-component/form`.
• gotcha `rc-field-form` specifies `react@>=16.9.0` and `react-dom@>=16.9.0` as peer dependencies. Running with older versions of React or ReactDOM will lead to runtime errors, particularly with the `useForm` hook and other React features introduced in 16.9.0.
  Fix: Ensure your project's `react` and `react-dom` dependencies are updated to versions `>=16.9.0`.
• gotcha By default, the `Form` component does not preserve field values when a `Field` component is unmounted (e.g., due to conditional rendering or dynamic lists). The `preserve` prop on `Form` defaults to `false`.
  Fix: If you need to retain field values even after the `Field` component is unmounted, explicitly set `<Form preserve={true}>` or add `preserve={true}` to individual `Field` components.
• gotcha Previous versions (e.g., `@rc-component/form` prior to 1.5.0) contained bugs where `onValuesChange` did not correctly merge values, especially in complex or nested form structures. While fixed in more recent updates, ensure your `rc-field-form` version is compatible with these fixes if you rely on `onValuesChange` for reactive logic.
  Fix: Always upgrade to the latest stable version of `rc-field-form` and ensure its internal `@rc-component/form` dependency (if directly managed) is up to date to benefit from all bug fixes, particularly those related to `onValuesChange` and form data consistency.
• gotcha The `useForm` hook, like all React Hooks, must adhere to the Rules of Hooks. It must only be called at the top level of a functional component or a custom hook, not inside loops, conditional statements, or nested functions.
  Fix: Ensure that `const [form] = useForm();` is invoked directly within the body of your functional component, not within any logic that could conditionally prevent its execution or alter its call order.

Install

• npm install rc-field-form npm
• yarn add rc-field-form yarn
• pnpm add rc-field-form pnpm

Imports

• Form, Field
  wrong:

  const Form = require('rc-field-form');
  const Field = Form.Field;

  correct:

  import Form, { Field } from 'rc-field-form';

  Primary way to import the main Form component and the Field component for form elements. ESM is preferred.
• useForm
  wrong:

  const { useForm } = require('rc-field-form');

  correct:

  import { useForm } from 'rc-field-form';

  Imports the React Hook for programmatic control over form instances. Must be called inside a functional component.
• List
  wrong:

  import { FormList } from 'rc-field-form';

  correct:

  import { List } from 'rc-field-form';

  Imports the List component, typically used as `Form.List` within the Form, for managing dynamic arrays of fields.
• FormInstance, FieldData

  import type { FormInstance, FieldData } from 'rc-field-form';

  For TypeScript users, these types provide definitions for the form instance and field data structures, crucial for type-safe form manipulation.

Quickstart

This example demonstrates a basic login form with input fields, validation, initial values, and submission handling using `rc-field-form` components and the `useForm` hook.

import React from 'react';
import Form, { Field, useForm } from 'rc-field-form';

interface LoginFormValues {
  username?: string;
  password?: string;
  remember?: boolean;
}

const Input = ({ value = '', ...props }: React.InputHTMLAttributes<HTMLInputElement>) => (
  <input value={value} {...props} style={{ border: '1px solid #ccc', padding: '8px', borderRadius: '4px', width: '100%', boxSizing: 'border-box' }} />
);

const DemoForm: React.FC = () => {
  const [form] = useForm<LoginFormValues>();

  const onFinish = (values: LoginFormValues) => {
    console.log('Form submission successful:', values);
    alert(`Submitted: ${JSON.stringify(values, null, 2)}`);
  };

  const onFinishFailed = (errorInfo: any) => {
    console.error('Form submission failed:', errorInfo);
  };

  return (
    <Form
      form={form}
      initialValues={{ username: 'guest', remember: true }}
      onFinish={onFinish}
      onFinishFailed={onFinishFailed}
      style={{ padding: '25px', border: '1px solid #eee', borderRadius: '8px', maxWidth: '450px', margin: '30px auto', boxShadow: '0 2px 10px rgba(0,0,0,0.05)' }}
    >
      <h3 style={{ marginBottom: '20px', color: '#333' }}>Login</h3>
      <div style={{ marginBottom: '15px' }}>
        <label htmlFor="username" style={{ display: 'block', marginBottom: '8px', fontWeight: 'bold' }}>Username:</label>
        <Field name="username" rules={[{ required: true, message: 'Please input your username!' }]}>
          <Input id="username" placeholder="Enter username" />
        </Field>
      </div>
      <div style={{ marginBottom: '15px' }}>
        <label htmlFor="password" style={{ display: 'block', marginBottom: '8px', fontWeight: 'bold' }}>Password:</label>
        <Field name="password" rules={[{ required: true, message: 'Please input your password!' }]}>
          <Input id="password" type="password" placeholder="Enter password" />
        </Field>
      </div>
      <div style={{ marginBottom: '20px', display: 'flex', alignItems: 'center' }}>
        <Field name="remember" valuePropName="checked" trigger="onChange">
          <input type="checkbox" id="remember" style={{ marginRight: '8px' }} />
        </Field>
        <label htmlFor="remember">Remember me</label>
      </div>
      <button type="submit" style={{ padding: '12px 25px', backgroundColor: '#007bff', color: 'white', border: 'none', borderRadius: '4px', cursor: 'pointer', fontSize: '16px' }}>
        Submit
      </button>
    </Form>
  );
};

export default DemoForm;