Upgrading to v2

Update your dependencies

Update @formiz/core and @formiz/validations packages to 2.x.x

yarn upgrade @formiz/core@beta @formiz/validations@beta

Update React react and react-dom (also @type/react and @type/react-dom if your are using Typescript).

yarn upgrade react@latest react-dom@latest
yarn upgrade -D @types/react@latest @types/react-dom@latest

Upgrade <Formiz />

👉 <Formiz> component doesn't accepts form actions definitions anymore. Now the only props that <Formiz /> accepts are connect and autoForm, and connect is required. Others props has to be past to useForm now.

Upgrade useForm

New usage

useForm has been split into 3 different hooks: useForm, useFormContext and useFormFields.

👉 useForm is still used for creating a new form like before. However, there is two changes :

• Now contains form actions definitions (like onSubmit for example).
• The subscribe property is gone, and the hook now only returns the form's state and actions.

✨ useFormContext is used to access the form's state and actions in a sub component. It will not create a new form so you can't connect it to a <Formiz> component.

✨ useFormFields is used to access fields states (not only values).

• Use it at top level with the connect option (useFormFields({ connect: form })) or in a sub component (without the connect option).
• Use a selector to get only the values (useFormFields({ selector: (field) => field.value })).
• Get only some fields with the fields options (useFormFields({ fields: ['myField']))

const MyForm = () => {
  const form = useForm();
 
  console.log({ values: form.values }) // ❌ Doesn't work anymore
 
  const handleSubmit = (values) => {
    console.log({ values })
  }
 
  // ❌ Formiz doesn't accept form actions anymore
  return <Formiz connect={form} onSubmit={handleSubmit}> 
    <MyChildren />
    <MyField name="myField" />
    <MyField name="myOtherField" />
  </Formiz>;
};
 
const MyChildren = () => {
  const form = useForm({ subscribe: { fields: ['myField'] } }); // ❌ Doesn't get the form anymore
 
  console.log({ form.values }) // ❌ Doesn't work anymore
 
  return <>
    {/* your code here */}
  </>;
};

const MyForm = () => {
  const form = useForm({ onSubmit: (values) => { // ✅ Form values passed in useForm
    console.log({ values })
  }}); 
 
  const values = useFormFields({
    connect: form,
    selector: (field) => field.value, // ✅ Get only the values
  });
 
  console.log({ values }); // ✅ { myField: 'my field value', myOtherField: 'my field value' }
 
  return (
    <Formiz connect={form}>
      <MyChildren />
      <MyField name="myField" />
      <MyField name="myOtherField" />
    </Formiz>
  );
};
 
const MyChildren = () => {
  const form = useFormContext(); // ✅ Works
  const values = useFormFields({
    fields: ["myField"],
    selector: (field) => field.value,
  }); // ✅ Works
 
  console.log({ values }); // ✅ { myField: 'my field value' }
 
  return <>{/* your code here */}</>;
};

Form actions updates

👉 setFieldsValues renamed to setValues

• 👉 keepPristine option now defaults to true.
• ❌ keepUnmounted was removed. setValues will now always behave as if keepUnmounted was true.

👉 invalidateFields renamed to setErrors

👉 getFieldStepName renamed to getStepByFieldName

👉 nextStep renamed to goToNextStep

👉 prevStep renamed to goToPreviousStep

Upgrade useField

Validations API changes

👉 rule renamed to handler

👉 Validations don't run on falsy values by default anymore

• You don't need to check on every validation that you have a value (null, undefined, '' or false) if your field is not required
• If you want to check falsy values (like Formiz v1), just pass the checkFalsy option to true.
• Now validations are now executed against formatted value.

<MyField
  name="myField"
  validations={[
    {
      rule: (value) => !value || value === "something", // 🚫 `!value ||` useless with v2
      message: 'Value must be "something"',
    },
  ]}
/>
 
<MyField
  name="myOtherField"
  validations={[
    {
      rule: (value) => value === "something", // 🚫 Will not be trigger on falsy value with v2
      message: 'Value is required and must be "something"',
    },
  ]}
/>

<MyField
  name="myField"
  validations={[
    {
      handler: (value) => value === "something", // ✅ Only triggered if required pass
      message: 'Value must be "something"',
    },
  ]}
/>
 
<MyField
  name="myOtherField"
  validations={[
    {
      handler: (value) => value === "something",
      message: 'Value is required and must be "something"',
      checkFalsy: true, // ✅ Opt-in to check also falsy value
    },
  ]}
/>

Field props renamed

👉 onChange renamed to onValueChange

👉 debounce renamed to debounceValidationsAsync

This will only debounce the async validations and not the value anymore. This prevents a lot of weird behaviors that were existing in v1. Now the value is handled by React v18 to optimize renders.

👉 asyncValidations renamed to validationsAsync

useField params renamed

👉 validating.start() renamed to externalProcessing.start() and 👉 validating.end() renamed to externalProcessing.end()

Types changes

You can now type the value of useField by passing a type to the FieldProps type. Also the otherProps will now be typed correctly 🎉.

// ✅ Pass the value type here ------------------------- 👇
type MyFieldProps<FormattedValue = string> = FieldProps<string, FormattedValue>
 
const MyField = <FormattedValue = string,>(props: MyFieldProps<FormattedValue>) => {
  const { value, setValue, otherProps } = useField(props);
  //...
};

The formatted value is by default the same that the value, but you can dynamicly override it.

<MyField<boolean>
// ------- 👆 I need to specify that my formatted value 
// Because I format my value to another type 
// ----------------- 👇
  formatValue={v => !!v}
/>

Not implemented yet in beta

• stateSubscription for useForm and useFormContext

  At the moment, both useForm and useFormContext will always return the full form's state. The stateSubscription option will allows to only return parts of the state, in case you need to further optimize renders on heavy forms.