criteriaMode: formLevel

[bluebill1049]

Context

React Hook Form focus on performance and user experience, which is a result of why the lib has quite precise on when to re-render your components. For example, if the input contains an error, we will trigger exactly one re-render to info the component to update, and exactly one re-render when the input's error gets resolved (instead of spamming the re-render). This is one of the reasons hook form is unique and more performant than most of the form libraries in the industry. The also reflects on form state update. However, we would like to expand that option to users, and allow users to have validation at the form level. So what are some of the impacts on such config:

Props

• User will be able to watch the entire form level validation errors
• Schema errors will be returned as a whole without any optimization or omit
• Works both with build-in and schema validation
• There are cases where custom resolver can be skipped

Cons

• If such config is turned on, the form will be less performant, which means each keystroke will hitting the validation rules and trigger more re-render to make sure all errors are presented for the entire form.
• More code to maintain and package size
• validation strategy mode & reValidateMode will be ignored

Proposal

useForm({
  criteriaMode: 'formLevel', // other options: firstError, all
})

Related issues

#4356
react-hook-form/resolvers#243

cc @jorisre @kotarella1110 @barrymay

[wdfinch]

Sounds good to me. Two questions:

Would these errors be placed in the formState.error object?
How would trigger be affected by this?

[bluebill1049]

Would these errors be placed in the formState.error object?

Yes,

How would trigger be affected by this?

will always return the form errors

[wdfinch]

Ok nice. Ya sounds good to me.

[bluebill1049]

actually trigger shouldn't be affected at all. the functionality stays as it is.

[bluebill1049]

Question: do we need to flush out all the form errors when the inputs are mounted or until the user interacts with the inputs?

The difference is pretty much whether we invoke trigger() instead of the lib at useEffect, or actually give users the option and when and what to fire the trigger at their app level.

[wdfinch]

I think when the user interacts with the inputs. This is how regular errors work. We add to the errors object once the user interacts.

[wdfinch]

I made a feature request for showing the errors on the same cycle as isValid but this is a separate use case and feature in my mind.

[bluebill1049]

With formLevel option, this will ignore the mode/reValdiateMode option as well, because all errors will be returned by the hook.

[bluebill1049]

updated in the con section as well.

[barrymay]

I'm a little confused by this one, although I think I like the idea - can you explain how you would document/explain formLevel vs the existing firstError vs all? (a table comparison might help, as in what setting has what behavior)

If it's what I think it is, I can see this being a commonly desired behavior and one the devs would sacrifice perf for vs the clearer user behavior. I feel I've likely made my forms work this way at times using mode and revalidateMode but having this more "built in" would be nice.

[wdfinch]

Sure what do you want to see in the sandbox?

[bluebill1049]

this example: #6472 (reply in thread)

[bluebill1049]

I can summarise the (DX) issue into two categories:

• parent field errors (schema)
• field array parent errors (schema)

will need to try to unlock the first improvement first before going to field array

[wdfinch]

Sure. I'll work on it tonight.

[wdfinch]

@bluebill1049 here you go. This is interesting, it seems like object errors are actually reported in formState.errors as expected. In the example, I run some validation on an object that contains fields and the error gets reported correctly with a path that is not a path to a rendered input. Not sure if this is a bug or the intended behavior. So maybe the issue here is just with field arrays then?

https://codesandbox.io/s/distracted-elbakyan-epkn8?file=/src/App.js

[wdfinch]

I'm not sure how this is a performance hit. The reason being is that we decide what validation we want to perform. All this is really doing is giving us access to errors that are already being computed by our validation (to get formState.isValid right).

Perhaps with built-in validation, it's more expensive if there are some optimizations. However, with schema validation, it is still being run the way we decide each time. For example, the user can use the abortEarly option in joi to stop after the first validation failure.

If anything this seems like it would be faster because we don't remove parse the schema result object and remove non-field errors. As mentioned above we can return it closer to how it is.

[bluebill1049]

thanks, @barrymay that would solve the problem for in build validation field array, at the same time I try to avoid more APIs for the library if we can. for build in validation, the easier way is just at the useEffect and set an error.

[barrymay]

that's very fair, maybe this is just put on the RHF website as a implementation example (if one's not there already for this case)

[bluebill1049]

Will do 👍

[bluebill1049]

react-hook-form/documentation#680

[wdfinch]

But we have the mode option on useForm. Couldn't the user just set this to onSubmit or something other than onChange? To me, this feature isn't about when we run validation but rather what errors get included in the formState.errors object

[wdfinch]

One question I have is should we place this under criteriaMode? To me, it seems like this controls something different.

For example, we could have multiple form-level errors.

Ex: we want to make sure a field array that consists of a single text input has at least 4 inputs and all the text in the inputs are unique. With the formLevel option would it behave like firstError or all? In other words, would we get back 1 or 2 assuming errors both validation rules fail?

To me, this seems like something that either should be set by default or a separate option. Again given my performance note above, I'm not sure how adding this would affect the performance. For example, if you don't care about form-level validation, then don't add any validation rules. Otherwise, we are already doing the work to compute it so I don't see how giving us the error message adds much more work.

[bluebill1049]

what's your suggestion?

[wdfinch]

I think this could just be the default behavior. If we write logic to validate at form level (a field array has 1 element), then I don't see how it hurts to include this information in the formState.errors object. In other words, if you don't want the validation, then don't write it. We are just giving people more information rather than omitting error messages. Whether the user wants to display the message is up to them. If anything it makes the logic easier because you don't need to parse the result of the schema validation and remove errors that don't relate to a field. Plus we still run the form level validation to compute formState.isValid.

Regarding performance, see my note above. I don't see why this needs to run on each keystroke and the user can't choose the mode option. This change is about not removing errors from the errors object rather than when we run the validation.

[wdfinch]

I guess the way I see this working, is we simply don't omit paths from formState.errors. For example, if we validate our form in joi and I require that a field array must have at least 1 element, then I get an error object that looks somewhat like this after running scehma.validate(getValues):

{
  context: {limit: 1, value: Array(0), label: 'myFieldArray', key: 'myFieldArray'}
  message: "\"myFieldArray\" must contain at least 2 items"
  path: ['myFieldArray']
  type: "array.min"
}

So therefore what I would like to see is in my formState.errors object is:

{
  myFieldArray: {
    message: "\"myFieldArray\" must contain at least 2 items",
    type: "array.min"
  }
}

Whether we use criteriaMode to show multiple errors or a single error is independent of this.

[bluebill1049]

For formlevel we are basically calling trigger on each keystroke, similar to most of controlled form validation lib. Just keep flush out all the schema errors.

[wdfinch]

Gotcha. See notes above regarding this.

[Mimameid]

I'm not quite sure if it is related to this topic, but since I got linked to here from 6858 and I see that fieldArrays are also part of this I wanted to add my 2 Cents here.

After digging a bit deeper into my confusion about 6858, I figured, that validation is working differently if the input is field level. When I compare it with field arrays: In both validation does run as defined in mode, though for fieldArrays the errors aren't reflected in the formState immediately, but only after submit. While this works for field level input. I can't find a documentation about this behavior. You can find an example in the link.

Is this related? If so, how come the validation is run anyway, but the error is not stored/reflected?

[wdfinch]

That's just the way it works. formState.isValid is based on the true result of the validation. So in schema validation, this means formState.isValid = schema.validate(formValues).isValid. Not the exact code, but this is the idea.

The errors object however only shows errors that relate to user-level input fields. So field array errors are not included because a field array is not a user-level input. The fields within a field array myFieldArray.0.name are user-level inputs, and errors for these are added to formState.errors.

The goal of this feature is to change this so we can get full access to all the errors whether they are related to a user input or not.

[bluebill1049]

here is an improved version: https://codesandbox.io/s/react-hook-form-fieldsarray-yup-validation-forked-6f6ih?file=/src/src/useFieldArray.ts

• The library will still respect the validation strategy (mode), we will not pass full errors to the form.
• useFieldArray now validate the entire field array with schema validation parent node, so each action will report if there is a group error
• Checkbox/radio or group inputs validation will be reported

[wdfinch]

Looks great! Nice job. I think if we could just get field array errors like in the sandbox then this would solve the problem for almost all the users (including myself). Thanks for doing this.

[franksimon90]

@bluebill1049 the trigger("*question*") on line 51 is intended, or it's just a typo? Current behavior for me is still confusing, if you add n fields, and focus on some k, start getting errors for k...n fields, everything bellow is valid. I managed to mark all the fields as invalid using controlled components here, but I'm pretty sure that the approach that I took on that sandbox is wrong, any suggestions?