Final Form

Common errors

• TS2345: Argument of type 'Partial<FormState<T>>' is not assignable to parameter of type 'FormSubscription'.

  cause Attempting to pass a partial FormState object as a subscription parameter instead of a FormSubscription object.
  fix Ensure that the second argument to `form.subscribe` is a `FormSubscription` object, where keys are state properties and values are booleans indicating subscription interest, e.g., `{ values: true, errors: true }`.

• TypeError: createForm is not a function

  cause Incorrect CommonJS `require` syntax or mixing CommonJS with ESM in a module that expects ESM imports.
  fix Use ES module import syntax: `import { createForm } from 'final-form';`. If in a CommonJS-only environment (e.g., older Node.js scripts), ensure your bundler or environment correctly transpiles ESM or use dynamic import if supported.

• Property 'someField' does not exist on type 'FormState<MyFormData>'. Did you mean 'values'?

  cause Directly accessing field values on the `FormState` object rather than through the `formState.values` property.
  fix Access form values via `formState.values.someField` and errors via `formState.errors.someField`. `FormState` itself contains metadata about the form, not the field values directly.

Warnings

• breaking Version 5.0.0 converted the entire library from Flow to TypeScript. While no *intentional* API breaking changes were introduced, developers relying on Flow types or intricate type inference might experience minor issues or require adjustments to their TypeScript configurations. Always test thoroughly when upgrading.
  Fix: Review TypeScript definitions in your project, especially if you had custom type augmentations for previous Flow-typed versions. Ensure your `tsconfig.json` is compatible and rebuild your application.
• gotcha Final Form's subscription model is powerful but requires careful selection of subscribed state. Subscribing to too much state can negate performance benefits, while subscribing to too little might cause components not to re-render when expected.
  Fix: Always explicitly define which form state properties (e.g., `{ values: true, errors: true, dirty: true }`) your component needs to re-render. Avoid subscribing to `everything: true` unless absolutely necessary for debugging or specific scenarios.
• gotcha Asynchronous validation in Final Form can sometimes lead to unexpected behavior, such as errors not clearing or validations running at incorrect times, especially if not handled correctly with debouncing or when field values change rapidly.
  Fix: Ensure your async validation logic correctly returns promises and handles their resolution/rejection. Review the official documentation on `asyncValidate` and consider debouncing your validation function for better user experience and to prevent validation 'races'.
• gotcha The `allValues` argument for `FieldValidator` was made optional in v4.20.7, but this change was reverted in v4.20.9. This inconsistency might cause type errors or unexpected runtime behavior if your validation functions rely on its optionality or presence across these specific versions.
  Fix: If using versions 4.20.7 or 4.20.8, explicitly handle `allValues` as potentially undefined or ensure your validator functions are robust to its presence. For optimal type safety, upgrade to >=4.20.9 where `allValues` is consistently required or check documentation for current behavior.

Install

• npm install final-form npm
• yarn add final-form yarn
• pnpm add final-form pnpm

Imports

• createForm
  wrong:

  const createForm = require('final-form')

  correct:

  import { createForm } from 'final-form'

  ESM is the recommended import style. CommonJS `require` is generally discouraged in modern applications and may lead to issues with bundlers or tree-shaking.
• FormApi
  wrong:

  import { FormApi } from 'final-form'

  correct:

  import type { FormApi } from 'final-form'

  FormApi is a TypeScript type representing the form instance. It should be imported as a type for type-checking purposes only. Importing it as a value will result in a runtime error or unnecessary bundle size.
• FieldState
  wrong:

  import { FieldState } from 'final-form'

  correct:

  import type { FieldState } from 'final-form'

  FieldState is a TypeScript type for the state of an individual field. Like FormApi, it should be imported as a type.

Quickstart

This quickstart demonstrates how to create a basic form instance with initial values, onSubmit and validation logic, and subscribe to form state changes using `createForm` from `final-form`.

import { createForm } from 'final-form';

interface MyFormData {
  firstName: string;
  lastName: string;
  age: number;
}

const form = createForm<MyFormData>({
  initialValues: { firstName: 'John', lastName: 'Doe', age: 30 },
  onSubmit: async (values) => {
    await new Promise(resolve => setTimeout(resolve, 500));
    console.log('Form submitted with values:', values);
  },
  validate: (values) => {
    const errors: Partial<MyFormData> = {};
    if (!values.firstName) {
      errors.firstName = 'Required';
    }
    if (!values.lastName) {
      errors.lastName = 'Required';
    }
    if (values.age < 18) {
      errors.age = 'Must be 18 or older';
    }
    return errors;
  },
});

const unsubscribe = form.subscribe((formState) => {
  console.log('Form State Changed:', {
    values: formState.values,
    errors: formState.errors,
    valid: formState.valid,
    dirty: formState.dirty,
    submitting: formState.submitting,
  });
}, { values: true, errors: true, valid: true, dirty: true, submitting: true });

// Simulate user input
form.change('firstName', 'Jane');
form.change('age', 17);

// Simulate form submission
form.submit();

// Cleanup (in a real app, this would be on unmount)
// unsubscribe();