Upgrading to v2

Update your dependencies

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

yarn upgrade @formiz/core @formiz/validations

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']))

Formiz v1

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

Formiz v2

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 false.
❌ 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.

Formiz v1

<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"',
    },
  ]}
/>

Formiz v2

<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

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.

Getting started Core