RFC: V8

[bluebill1049]

V8

We will try to ensure good backward compatibility, which means we will try to ship most of the new features at V7 and migrate over to V8.

---

• ⚠️ reset

• remove keepIsValid for reset options

reset({ data: 'test' }, {
-  keepIsValid: true
})

Rationale: valid formState should always reflect the current form valid state instead of being manipulated and causing unexpected behavior.

• remove internal reset API invoke

const { reset } = useForm(); // without defaultValues 
- reset() // not recommend to reset form with empty argument
+ reset({ data: 'test' })

Rationale: by providing what your form should be reset to ease the issue with undefined value and also making sure type safety is much easy measured instead of DeepPartial

• ⚠️ useFieldArray

• prop keyName will be removed and no longer required

const { control } = useForm({ defaultValues: { test: [ {id: 123, name: 'test' } ] } })
- uesFieldArray({ name: 'data', control, keyName: 'otherNmae' })
+ uesFieldArray({ name: 'data', control }) // works without the need to change `keyName`

Rationale: field id is no longer required in V7 https://github.com/react-hook-form/react-hook-form/releases/tag/v7.23.0 and this is so we can reduce configuration

• ⚠️ useController & getFieldState

• remove fieldState invalid

- const { fieldState: { invalid } } = useController()
+ const { fieldState: { error } } = useController() //  use error object instead
- const { invalid } = getFieldState('test')
+ const { error } = getFieldState('test')

Rationale: API consistency #8195 user should be able to use the error object directly and avoid this inconsistency

• ⚠️ useFieldArray

considering changing key name from id to key

Rationale: to ease the id value overwrite issues.

- <div key={field.id} />
+ <div key={field.key} />

• ✨ useFieldArray

• prop rules will be added for field array level validation

close: #6879

useFieldArray({
  name: 'test',
  rules: {
    required: true,
    minLength: 2,
    maxLength: 10,
    validate: (fieldArrayValues) => {
      if (fieldArrayValues) {
        return 'valdiate Error'
      }
    }
  }
})

errors?.test?.root?.message

Rationale: now that the errors object type is improved and we can support field array root level error object. Adding root to the array index may affect the array prototype, but considering the usage of the errors object, I think it's a worthy trade-off rather introduce a separate node for field array root level errors.

---

• ⚠️ handleSubmit will infer formValues and UseFormHandleSubmit generic is no longer required. onValid and onInvalid payload both will be readOnly Don't expose internal errors reference in handleSubmit #7718
• ⚠️ If useForm's defaultValues is provided, then it's no longer deep partial to support better type checking (this is not impact inline defaultValue/defaultChecked)
• ⚠️ removed NesetedValue and use getFieldState for neseted object input instead
• ⚠️ TriggerConfig rename to TriggerOptions
• ⚠️ SetValueConfig rename to SetValueOptions
• ⚠️ requires TS 4.5 above
• ⚠️ upgrade to es2020

---

PR: #5941

✨ Added
⚠️ Breaking change
🥼 Change

[wdfinch]

setValue will no longer update entire field array (focus on inputs level), use replace, update from useFiedlArray instead

One issue with this is when I need to update a field array index and I'm within a nested component. For example I wanted to update a field array index from within <FormComponent/> below:

fields.map((field, index) => (
  <FormComponent key={field.id} field={field}>        
))

Inside the component, I can easily grab setValue from useFormContext. Because there is no field array context, I would need to pass around an onUpdate callback or make my own context to move it around.

I would rather use the update method on the field array, but would you consider adding a field array context to move those methods around if you are taking functionality away from setValue?

[mikestopcontinues]

One additional problem with getting rid of keyName is that it exacerbates the sorting problem. And if you disable setValue for array fields, that effectively prevents sorting entirely. For any list long enough, sorting is essential for usability.

[bluebill1049]

@mikestopcontinues key will always be there, you don't need to rename keyName anymore.

[mikestopcontinues]

@bluebill1049 Ah thanks. I've been using array field for the first time today, so I was mostly climbing up the learning curve earlier. 😅

[bluebill1049]

no worries, just try to make the DX for field array a bit easier. less config for all of us.

[david-morris]

Hey, I've got another use-case that could cause a problem with desupporting the use of setValue for field arrays. I noticed this change was planned from reading the documentation.

I've got a complicated form because I'm developing a webapp, and I have a template operation for one particular stage of the app. Users can load templates to simplify expressing a many-to-many relationship whose definition is part of the product we're selling.

If I were to use replace instead of setValues I would have to move my template menus down or smuggle a ref to replace up. I don't think that's ideal because that would be contradicting the React Docs' recommendation to avoid passing around refs to "make stuff happen."

It makes sense to me that "external" manipulations of a list of form data should be possible. And I've been using react-hook-form as a single source of truth and a unified API --- fragmenting that API and making me move state around where I didn't before would make my code a lot harder to understand.

[bluebill1049]

Proposal for field array context API:

https://codesandbox.io/s/react-hook-form-v7-form-context-forked-7ng26?file=/src/index.js

import React from "react";
import ReactDOM from "react-dom";
import { useForm, FormProvider, useFieldArray } from "./src";
import Test from "./Test";

import "./styles.css";

function App() {
  const methods = useForm();
  const { register, handleSubmit } = methods;
  const testFieldArray = useFieldArray({
    name: "data",
    control: methods.control
  });

  console.log("render...");

  return (
    <FormProvider
      {...methods}
      arrays={{
        test: testFieldArray
      }}
    >
      <form onSubmit={handleSubmit((data) => console.log(data))}>
        <label>Test</label>
        <input {...register("test", { required: true })} />
        <label>Nested Input</label>
        <Test />
        <input type="submit" />
      </form>
    </FormProvider>
  );
}

export default function Test() {
  const methods = useFormContext();

  return (
    <>
      <input {...methods.register("bill")} />

      {methods.arrays.test.fields.map((field, index) => {
        return (
          <input key={field.id} {...methods.register(`data.${index}.test`)} />
        );
      })}

      <button onClick={() => methods.fieldArrays.test.append({ test: "data" })}>
        append
      </button>
    </>
  );
}

[wdfinch]

Looks good! I like it.

[bluebill1049]

perhaps we should have a separate method to update field array methods, so they can still sit in their own component level, without needing to hoist to the parent component. obviously the execution order matters.

const { updateFieldArray } = useFormContext()

updateFieldArray('name', methods)

[bluebill1049]

just some thoughts at the moment, this feature will be cross v7 and v8.

[timkindberg]

As long as I'm not forced to hoist field/array declaration to the form level then I think it's ok.

[bluebill1049]

you will have to if you want to use context.

[wdfinch]

I'm not sure if I'm just missing something here, but it seems like the direction the library is moving is to separate methods that alter field array fields vs regular fields.

If this is true, I like this but I feel like some things are missing from the field array methods if this is the case:

1. setValue equivalent - you pass a field name and index along with a new value and it changes that specific field's current value.
2. reset equivalent - at the element, entire field array, and individual field level.

By reset I mean the ability to not only change the default value but the metadata as well. With conditionally rendered fields in field arrays, I'm not seeing too many options other than reset to clear validation for unmounted inputs. This would also by true for other meta values like isTouched and isDirty.

I'm not sure if it makes more sense to add new methods or update methods like replace + update to give more control over meta properties. For example being able to pass in an object like {keepErrors: boolean, keepDirty: boolean, ...}

[wdfinch]

So for the useFieldArray methods something like:

setFieldArrayField -> set and individual field input -> equivalent to setValue('root.1.test.fieldLevel')
resetFieldArrayField -> change default value and meta state for individual field array field
resetFieldArrayElement -> change default values and for meta state for a field array element
resetFieldArray -> change default values and for meta state for the entire (root) field array

This seems to fill in the gaps I'm noticing with the field array API. Not suggesting these exact methods. Just the idea is all.

[wdfinch]

yes, that should be the direction.

Ok cool. I like this a lot. Resetting field array stay to get rid of errors when unmounted is currently where I'm struggling the most right now.

[bluebill1049]

sounds good. Let's look into this and find APIs to cover those scenarios. Those can be slowly applied to v7.

[bluebill1049]

Resetting field array stay to get rid of errors when unmounted is currently where I'm struggling the most right now.

i don't understand above.

[wdfinch]

i don't understand above.

No worries, I think we covered everything we needed.

[bluebill1049]

cc @Moshyfawn you may want to be participate and aware of the general direction with v8.

[Moshyfawn]

I've been meaning to participate for a couple of days now, just can't get the time to do it :(

[bluebill1049]

#7433 (reply in thread)

useFieldArray ^

[bluebill1049]

it's a difficult one especially with native input, so if you want to achieve that unregister method is the safe bid.

[wdfinch]

I see. The issue with unregister is it removes the default value. I guess I'm looking for a way to unregister an input on unmount or programmatically with the exception that the default value is kept in form state. Everything else I want gone. I've been using resetField to do this but if I can't clear the error, that's gonna be an issue.

[bluebill1049]

unregister('whatever', { keepDefaultValue: true }) ?

[wdfinch]

Ya, that could work.

[wdfinch]

That would also solve the issue with the shouldReset prop I suggested. I just need a way that when field and field array inputs unmount, I can keep the default value but get rid of everything else.

[wdfinch]

remove all the should* and is* preFix

I'm not sure how I feel about this. Yes, it is less verbose but less verbose isn't always better. I like prefixing booleans with is and should because it's more readable and this is a big breaking change for not much benefit in my opinion.

[bluebill1049]

This is always a two side coins thing, for me typescript is here to determine the type if it's boolean or other types.

[wdfinch]

I agree, I just think from a code readability standpoint is nicer to see is and should be prefixed to boolean values. I think it makes it clearer since you don't need to hover over it to learn the type. You can guess just by reading it.

[bluebill1049]

yea, I agree with that which is the original reason why I added those prefixes, so it's readability for JS developers but over the years more and more users jump into TS. If I hear a lot voice against this happy to remove and revert the change tho.

[wdfinch]

Ya at the end of the day, it doesn't matter that much either way. Some people might be unhappy about having to refactor a bunch of code just because of a name change.

[bluebill1049]

reverted and not going to change that.

[matamatanot]

This is just my personal opinion, I want to keep using keyName.
There are some cases where id is selected by select.option and it will be the same value.

[bluebill1049]

keyName is no longer required because what hook form produced as key id is no longer a part of your form values, you can still pass your own input value as field id and it will not overlap. This is already the case in V7 today.

[matamatanot]

you can still pass your own input value as field id and it will not overlap.

In my use case, the id field can be entered by the user, so there are moments when the values are the same. React warns of an error about duplicate keys.

[matamatanot]

[matamatanot]

   {displayNameTranslationsFields.map((item, index) => {
              return (
                <HStack as="li" key={item.id}>
                  <FormControl w={"20%"}>
                    <FormLabel>{`Language(ID)`}</FormLabel>
                    <Select
                      {...register(`displayNameTranslations.${index}.id`)}
                    >
                      <option value={"ja"}>{"Japanese"}</option>
                      <option value={"fr"}>{"French"}</option>
                    </Select>
                  </FormControl>

<HStack as="li" key={item.id}>
This is where the error occurs.

keyName: "identification" <HStack as="li" key={item.identification}>
The error can be avoided by using keyName.

[bluebill1049]

yep, then the id field will be retained. your use case will not break.

[Moshyfawn]

const { reset } = useForm(); // without defaultValues 
- reset() // not recommend to reset form with empty argument
+ reset({ data: 'test' })

What do you think about starting to emit console warnings for these cases? Like, for RHF usage that's "discouraged"?

[bluebill1049]

we did that for v6, it has pros and cons. Some users complain it's annoying, even the warning is valid... The other downside is ES module wouldn't be able to remove those logs for the prod build.

[RobertAron]

The new field path prevents registrations on conditional fields

https://codesandbox.io/s/agitated-frost-hz9gcx?file=/src/App.tsx

Is there a different method for registering to those now?

[bluebill1049]

@felixschorer I believe this is a union-type bug.

[felixschorer]

This is actually working as intended. RHF can't model conditional properties like that.

• If you toggle conditionMet off, someValue will still be part of the model.
• If the default state is { conditionMet: false } and you toggle it on, the input component will receive undefined as the initial value for someValue even though someValue should never be undefined according to the type.

It gets worse once you throw nested properties into the mix.

Why does the type guard not work as expected?

{vals.conditionMet === true && (
  <input {...register("someValue")} placeholder="First Name" />
)}

This check only proofs that vals is of type ConditionMetType, but register has captured the FormType type. I.e. you would have proof that register is of type UseFormRegister<ConditionMetType>.

How can I implement discriminating unions then?

You don't 😅 You need to flatten your union into a single object.

type FormType = {
  conditionMet: boolean;
  someValue: string;
};

That stays faithful to the internal model of RHF.

Complex example

TS Playground

type Model= 
    | { type: 'person'; name: string; firstName: string; dateOfBirth: Date}
    | { type: 'company'; name: string; legalForm: string; foundingDate: Date }

type FormFields = {
    type: 'person' | 'company';
    name: string;
    person: { firstName: string; dateOfBirth: Date };
    company: { legalForm: string; foundingDate: Date };
}

function toFormFields(model: Model): FormFields {
    switch (model.type) {
        case 'person': {
            const  { type, name, firstName, dateOfBirth } = model
            return {
                type,
                name,
                person: { firstName, dateOfBirth },
                company: { legalForm: 'Ltd.', foundingDate: new Date() },
            }
        }
        case 'company': {
            const  { type, name, legalForm, foundingDate } = model
            return {
                type,
                name,
                person: { firstName: '', dateOfBirth: new Date() },
                company: { legalForm, foundingDate },
            }
        }
    }
}

function toModel(formFields: FormFields): Model {
    switch (formFields.type) {
        case 'person': {
            const  { type, name, person } = formFields
            return { type, name, ...person }
        }
        case 'company': {
            const  { type, name, company } = formFields
            return { type, name, ...company }
        }
    }
}

[bluebill1049]

thanks @felixschorer for the detailed reply! ❤️

[bluebill1049]

This makes a lot of sense as there is no way for hook form to discriminate the union type unless during the run time check.

[bluebill1049]

FYI: @alec-pirillo-le

[Moshyfawn]

Rationale: Semantically it's confusing where setValue can replace an entire field array, its responsibility should be just to update the field. At a time when setValue was the only solution due to replace and update API was missing.

Kinda a breaking change, but what do you think about renaming setValue to setFieldValue? We have resetField to reset an individual field. setField might not be as descriptive, so.. setFieldValue

[KurtGokhan]

I am trying version 8 and I have a question about the keyName change. How to get the real id of the field now that the id is overwritten by RHF? With typescript, If I have an id: number in the original field type, the id in the field array becomes never and is not usable. Even if the default key name was changed to key, this could happen for someone else who has key as original property.

I have been thinking about this but wouldn't it be easier if field was represented as id - field pair (or aptly key - value pair) instead of merging them together? Alternatively, id could be a symbol. Or fields can be an array-like with custom map which exposes id as third parameter. These are just ideas though, but the current way sounds confusing. Since this is a major release, such a breaking change could be appropriate. What do you think?

I can work on it if you give me greenlight.

[bluebill1049]

thanks for the contribution: #8197 change key name from id to key

[bluebill1049]

propose to change reset optional API: #8233 (reply in thread)

[nandorojo]

Is there a replacement for FieldPath in v8? I notice that it no longer results in any types when I pass FieldPath<{ name: string }> in v8.

If you toggle v7/v8 here, the autocomplete enters/disappears: https://codesandbox.io/s/react-hook-form-js-forked-5r2bu3?file=/src/App.tsx

[felixschorer]

You'll have to call of now.

const path: FieldPath<{ id: number }> = of('id')

[DKuhse]

V8 is looking great, thanks for the hard work. I'm not aware of any other library supporting type safe subforms. I've encountered a small type regression though:
UseFormRegister is now bivariant, so given any types A and B, it's possible to cast between UseFormRegister<A> and UseFormRegister<B>.
Small example:

const a : UseFormRegister<{a : number}> = 0 as any;
const b = a as UseFormRegister<{b : string}>;
const c : UseFormRegister<{a : number}> = b;

This makes passing register potentially hazardous.
Is there an ETA for the release of V8? The ideal fix would be to mark it as invariant on the parameter by prefacing it with in out:
type UseFormRegister<in out TFieldValues extends FieldValues> = ...
However this would require TypeScript 4.7, which only gets released later this month (one can try out the fix using the release candidate).
If V8 is released soon-ish, I imagine this solution might not be the best, but I don't know of any other way.

[Moshyfawn]

No ETA for now

[quicksnap]

Discussed in #8510, Partial/DeepPartial typing should be removed. If developers actually want their fields to be potentially undefined, typing it correctly and providing the essential default values will help reduce avoidable runtime errors.

[quicksnap]

For deep nesting and variable forms, devs may still type things properly by nesting undefined throughout their types.

[mh-alahdadian]

whats the state of v8 ? what's the estimated time for releasing v8 ?

[bluebill1049]

hey @mh-alahdadian i think we are pausing it for awhile and keep rolling new updates on the current major version.

[cdbattags]

Hi folks, reading back through all of the progress on v8 now. We're looking to make the switch from Formik ASAP but the circular dependency issue with Type of property 'something' circularly references itself in mapped type is a blocker for us. I see that v8 is supposed to solve this but it looks like v8 is a long way away, correct?

Looking at 4.9 it seems like the solution at https://stackoverflow.com/questions/58434389/typescript-deep-keyof-of-a-nested-object/58436959#58436959 pretty much hits what we need, no? Happy to assist however I can.

[bluebill1049]

We have hit breaking change on 4.7 from TS and have to pause the v8 moving forward.

Looking at 4.9 it seems like the solution at https://stackoverflow.com/questions/58434389/typescript-deep-keyof-of-a-nested-object/58436959#58436959 pretty much hits what we need, no? Happy to assist however I can.

Looks interesting and PR is welcome! We will have to move forward with v7 for now, until we figure out something better for the next major update.

[csantos1113]

If useForm's defaultValues is provided, then it's no longer deep partial to support better type checking (this is not impact inline defaultValue/defaultChecked)

I've seen this in a few comments (#9954 (comment) and #9400 (comment)) and it scares me 😬

---

Say I have the following form:

country: 'CO' | 'US',
firstName: string,
lastName: string

And I want to have US as the default value for the "country" field every time the form is mounted, as well as when the form is reset

Currently I'd do:

const x = useForm({ defaultValues: { country: 'US' }, ...restProps })

But if I understand the proposal correctly, I'd need to move away from defaultValues and use defaultValue at the input level instead?

[david-morris]

So you still don't have a "blank" value for age in that type. That means you could read the age and expect it to be a number. This might be a problem if you decide to display some statistic, like So you should still start with some known value that doesn't pass validation but won't interfere with any algorithms.

You could make age optional, so you know you might get undefined. That's what probably makes the most sense here --- by making it optional, you will have typescript reminding you to check if that's really there and a number.

That's probably uncomfortable because you want your form type to match some graphql input type or something. But that means that you'll be reminded that you don't necessarily have that value in the form, and need to check.

[csantos1113]

Hey @david-morris - thank you for talking through this with me, I appreciate your help and time 🙏 That all makes sense, but let's keep evolving my example.

by making it optional, you will have typescript reminding you to check if that's really there and a number.

The idea is to validate the form using resolver and use yup for the schema (or any schema handler tbh):

import * as Yup from 'yup';
import { yupResolver } from '@hookform/resolvers/yup';

const schema = Yup.object({
  country: Yup.string().oneOf(['US', 'CO']).required(),
  firstName: Yup.string().required(),
  lastName: Yup.string().required(),
  age: Yup.number().required()
});

So react-hook-form validates the values for me out of the box before submission:

const x = useForm({
  defaultValues: { country: 'US', firstName: '', lastName: '' },
  resolver: yupResolver(schema),
});

and as of @hookform/[email protected] the types are inferred from that schema. So the inferred type from that will end up in what I had in my previous comment

type {
  country: 'CO' | 'US',
  firstName: string,
  lastName: string,
  age: number
}

---

So it all goes back to my original question 😞 how to support "partial" default values for a required type.

---

it sounds to me that we would need 2 explicit types Input/Entry/Default values; and Output values?

[timkindberg]

Zod has the concept of input/output for a particular schema if the schema may be transformed. Just bringing it up for some prior art. https://zod.dev/?id=type-inference

[david-morris]

@csantos1113 Hmm, this use case might be something I'm not familiar with. I don't use Zod.

Does Zod build the Typescript types itself? There's probably some LeafPartial in some library somewhere. That way you could DRY your types while representing with those types that the possible values of your form and the values which are legal to input into your form are different.

[msileo]

I will have the exact same issue using default values and Yup resolver. If I make the fields without default values optional, I'll have to update the Yup schema as well, which will then pass validation when it shouldn't. 😕

[maxkostow]

Hi team, happy new year - are there any updates to the status of v8 for 2025? In particular we are interested in the ts performance improvements.

Based on #5941 (comment) it seems the minimum tsc version would have to be bumped from 4.5 to 5.3?

[maxkostow]

For anyone curious - #12510 provides a huge ts performance improvement for large form types. We've patch-packed it into our repo since it is not yet published to npm.

[BrendanC23]

This is the current pull request for version 8, which includes support for the React compiler and renames the useFieldArray fields.id to fields.key.