Type-safe reusable sub-forms

[happenslol]

I want to create type-safe, reusable components for complex sub-forms.

Consider the following example:

type FormValues = {
  name: string
  address: Address
}

const MyForm = () => {
  const form = useForm()
  const handleSubmit = (data: FormValues) => console.log(data)

  return (
    <form onSubmit={form.handleSubmit(handleSubmit)}>
      <input {...form.register("name")} />
      <AddressInput form={form} name="address" />
    </form>
  )
}

type Address = {
  street: string
  city: string
  country: CountryCode
}

type AddressInputProps = {
  form: UseFormReturn
  name: string
}

const AddressInput = (props: AddressInputProps) => (
  <div>
    <input {...form.register(`${props.name}.street`)} />
    <input {...form.register(`${props.name}.city`)} />
    <CountrySelect control={props.form.control} name={`${props.name}.country`} />
  </div>
)

Now, I want to use AddressInput in different forms. To be able to use both register and control, it makes most sense to just pass the entire form object to the input. I can get type safety for the AddressInput.name prop by using FieldPathByValue:

type AddressInputProps<
  TFieldValues extends FieldValues,
  TPath extends FieldPathByValue<TFieldValues, Address>,
> = {
  name: TPath
  form: UseFormReturn<TFieldValues>
}

// "name" is now type checked and has autocomplete
<AddressInput form={form} name="address" />

However, since Typescript does not support narrowing generic string literals inside other literals, the following now throws an error:

// Inside AddressInput
<input {...props.form.register(`${props.name}.street`)} />

// Argument of type '`${TPath}.street`' is not assignable to parameter of type 'Path<TFieldValues>'.
//  Type '`${string}.street`' is not assignable to type 'Path<TFieldValues>'. [2345]

Even though props.name is of type TPath and the type `${TPath}.street` should satisfy FieldPath<TFieldValues>, it gets broadened to `${string}.street`. which does not.

It's also arguably unergonomic having to prefix every form field name with ${props.name} inside AddressInput, and the input theoretically has access to the entire outer form.

Possible Solutions

I can see multiple ways to solve this problem. Essentially, there would have to be a way to create a "sub-form" that is scoped to a specific field.
This could either be a function on UseFormReturn:

const { form: addressForm, name: addressName } = form.registerSubForm("address")
<AddressInput form={addressForm} name={addressName} />

// Or the shorthand:
<AddressInput {...form.registerSubForm("address")} />

Or a new useSubForm hook: that can be called from within AddressInput:

const AddressInput = (props: AddressInputProps) => {
  // The arguments here can be constrainted so that they only accept
  // FieldPathByValue<TFieldValues, Address>
  const form = useSubForm(props.form, props.name)

  // All fields within form are now scoped to the "address" field, including
  // watch, control, etc. - basically every path is prefixed with "address.".

  return (
    <div>
      <input {...form.register("street")} />
      <input {...form.register("city")} />
      <CountrySelect control={form.control} name="country" />
    </div>
  )
}

Alternatives

All alternatives I've considered make tradeoffs in type safety or performance:

1. It's possible to just pass a control to the AddressInput, but every update would rerender the entire component, which is fine in this case - but not when there are multiple nested fields even within a sub-component. It's also not possible to use register in this case.
2. It's possible to actually use sub-forms, but then all state (validation, dirty, touched, handlers) needs to be passed up, which is not ideal and not always possible.
3. The approach in the initial example is a possibility, but does not offer type safety and is unergonomic because every field needs to be prefixed.

---

I would love to use react-hook-form for a large project I'm working on, but we have lots of complex components with nested fields that are used in multiple forms.

Having an API like this would go a long way when it comes to composing forms from smaller, isolated parts, and even allowing libraries containing complex input components to be published.

If this is a feature you would consider, I'd be happy to take care of the implementation.

[bluebill1049]

you may find this useful: https://github.com/react-hook-form/lenses

[happenslol]

you may find this useful: https://github.com/react-hook-form/lenses

Oh, that's great, thanks!

That library seems to be doing pretty much what I outlined in the registerSubForm proposal, as a userland solution. The only gripe I have with that is that it directly accesses the control fields, which is advised against in the documentation - The library shows it in the examples though, so I suppose it's the intended usage?

This should at least be linked somewhere or more discoverable, since this is a very common usecase in larger applications IMO.

[bluebill1049]

@aspirisen perhaps we can figure out something to include in the main documentation. perhaps a section under advanced tab?

[aspirisen]

@bluebill1049 I am planning to start working on the documentation for the website this weekend

[happenslol]

While the linked library does offer a solution, it still feels to me like this functionality has a place in the library itself. The lens API does the job, but it's pretty unergonomic:

const lens = useLens(form)
const subForm = lens.focus("subField")
<input {...subForm.interop((ctrl, name) => ctrl.register(name))} />

It's also weird that the following is not a type error:

// Why does name not use e.g. a branded type?
// Or simply proxy the register method so that there's no name param, if there is only ever 1 allowed value?
interop((ctrl) => ctrl.register("__DO_NOT_USE_HOOK_FORM_CONTROL_SHIM__"))

I'm not sure how much of the API is dictated by the library being userland, so I suppose I'll raise that in the library instead of here.

So, is this usecase considered handled by virtue of the library existing?

[aspirisen]

@happenslol thank you for your feedback

About unergonomic - this is true in the example you provided, in such cases it is easier to just use register. The reusability approach that the lens library provides implies that you have shared form component, so you could have just provide lens to that form component

<StringInput lens={lens.focus('name')} />

Also, there is one often case that is covered in lens - ability to restructure the provided fields form. I.e. in your example AddressInput expects that in parent form there will be fields like street and city. But what if the parent form these fields have different names or placed in some other levels. In lenses you can solve this problem by using reflect method

About __DO_NOT_USE_HOOK_FORM_CONTROL_SHIM__ this is workaround for typings. I have to properly type the returned control. But in Control type you can't just pass a generic and say that this is the type of control. Also, the Control generic can't accept primitive and array types and also requires a valid prop path. By that __DO_NOT_USE_HOOK_FORM_CONTROL_SHIM__ I am able to deceive the Control type by passing the wrapper type and the path. For example the logic is like that

Control<{__DO_NOT_USE_HOOK_FORM_CONTROL_SHIM__: {real: {form: {type: string}}}}, '__DO_NOT_USE_HOOK_FORM_CONTROL_SHIM__'>

So the Control type receives object with __DO_NOT_USE_HOOK_FORM_CONTROL_SHIM__ field, and immediately selects it

[happenslol]

@aspirisen Thanks for your detailed response! To be clear, your library definitely covers my usecase, so maybe we can gain some improvements from the pain points I've hit here 🙂

About unergonomic - this is true in the example you provided, in such cases it is easier to just use register.

What do you mean by "just use register"? The lens itself does not have a register function from what I can see, so at some point down the tree I'll have to do interop((ctrl, name) => ctrl.register(name)) if the tree ends in a native input, no?

In your case, the StringInput would have to do that internally.

Also, there is one often case that is covered in lens - ability to restructure the provided fields form. I.e. in your example AddressInput expects that in parent form there will be fields like street and city. But what if the parent form these fields have different names or placed in some other levels. In lenses you can solve this problem by using reflect method

That's a usecase I hadn't thought of. reflect sounds super useful.

About DO_NOT_USE_HOOK_FORM_CONTROL_SHIM this is workaround for typings. I have to properly type the returned control. But in Control type you can't just pass a generic and say that this is the type of control. Also, the Control generic can't accept primitive and array types and also requires a valid prop path. By that DO_NOT_USE_HOOK_FORM_CONTROL_SHIM I am able to deceive the Control type by passing the wrapper type and the path. For example the logic is like that

I'll take a look at the internals of your library. I feel like in a best case scenario, I would be able to do the following:

type Schema = {
  name: string
  controlledField: { ... }
  complexObject: { ... }
}

const Component = (props: { lens: Lens<Schema> }) => (
  <div>
    <input {...props.lens.register("name")} />
    <ControlledField control={props.lens.control} name="controlledField" />
    <ComplexObject lens={props.lens.focus("complexObject")} />
  </div>
)

I'll check back here (or over on discussions/issues on the lens repo? Whatever you prefer) when I've had a chance to find out what tradeoffs would be needed to get there.

[aspirisen]

I'll check back here (or over on discussions/issues on the lens repo? Whatever you prefer)

I think it depends on you what do you want to achieve

<input {...props.lens.register("name")} />

Personally I would avoid providing the Control's methods like register, watch etc. in Lens class, just to make lens and control separate and do not depend on each other. That's why I added interop method - provide the control as is and let user to decide what to do with that and methods to call

[happenslol]

I think it depends on you what do you want to achieve

I'd like to have my usecase covered, with the most ergonomic API possible.

Personally I would avoid providing the Control's methods like register, watch etc. in Lens class, just to make lens and control separate and do not depend on each other. That's why I added interop method - provide the control as is and let user to decide what to do with that and methods to call

When I use a lens in a sub-component, I mainly want to do one of the following 4 things:

1. Use register to register a native field
2. Use control to register a controlled field
3. Pass the lens to another subform using lens.focus
4. Pass a restructured leens to another subform using lens.refocus

Now that I think about it, 2, 3 and 4 are already possible very easily:

// 2
const controller = useControl(lens.interop())
const controllerForSubField = useControl(lens.focus("subField").interop())
// 3
<SubComponent lens={lens.focus("subField")} />
// 4
<SubComponent lens={lens.reflect(...)} />

I could write a utility function myself that does this:

const registerNativeField = (lens, subField) => lens.focus(subField).interop((ctrl, name) => ctrl.register(name))

<input {...registerNativeField(lens, "firstName")} />

I just feels to me like there's nothing else you would want to (or should) call from the interop closure than ctrl.register(name), so I feel like having the above would be a lot more intuitive.

What do you think?

[aspirisen]

With duplicating react hook form api we will struggle with typings, especially if react hook form will change them. I would like not to bind lenses and rhf, just leave lenses simple to work as a cargo for control and name

[happenslol]

Seems it would make more sense for my proposal to be considered for react-hook-form directly then, since then there's full control over the types. Thanks for your input!

[Alletkla]

I'm very glad this feature request came up because I have the same need. 👍🏽

I am currently using this approach:

const BaseComponent() => {
  const methods = useFormContext()
  // Use everything inside here, as if it would be a normal component without nesting
}

const Component(prefix: string) {
 return (
    <SubFormProviderProxy prefix={prefix}>
        <BaseComponent />
    </SubFormProviderProxy>)
}

✅For me the advantages of this approach are:

• Keeps the "normal" API and documentation clean, for users who are not interested in using SubForms or starting to use react-hook-form
• Allows for endless nesting - without components explicitly knowing how deeply nested they are
• The Proxy can be maintained in isolation, if it becomes to hard to maintain in the future, it can be removed again without touching (to much) other code.
• Easy to adopt: Wrap your Components you are likely to need as SubComponents with the Proxy... done (in theory^^) - Rest is setting correct schemas and default values - but thats outside the heavy lifting.

❌Current disadvantages:

• cause WIP: not typesafe by now, uggghhh. I know: But maybe a future "registerSubComponent" method can do the heavy lifting on types, for extracting the given name out of the FormContext. But if you use schema validation a wrong prefix would pop out anyway (although only at runtime).

---

I kind of got the proxy working for my use cases, but I don't know if EVERY function is working correctly (probably not) because I'm developing on it right now.

My Proxy is basically utilising the fact, that react context always gets the nearest context it can get:

export const SubFormProviderProxy({prefix, children}) => {
  const parentMethods = useFormContext();

  const prefixedMethods = {
     // check if prefix is given.   and overwrite every method I need. e.g.:
    // Register fields with prefixed names
    register: (name: string, options?: RegisterOptions) => {
    	return parentMethods.register(prefixPath(name), options);
    },
  }
return <FormProvider {...(prefixedMethods)}>{children}</FormProvider>;
}

But I had issues with
⚠️ Why is useController utilising the given name (line 151) in the Controller prop and not the return value of control.register (Line 76)?
On Blur, on Change seem to utilise the return of control.register. Because of that the Name stays the same, because I see no chance, to keep the components without modification and change the name Prop. So my current workaround is:

<Controller
      control={control}
      name={register(name).name}
      //rest
>

-> I don't know if this double registration (here explicit, later implicit by controller.register) causes any trouble besides some performance overhead, for me - in my WIP state - it is not.

👉🏽 This is getting to be a long comment already. I just wanted to outline my solution to this problem a bit.
Since I've just started digging deeper in the library - maybe I'm missing something that makes this approach too hard to handle, but if you're interested, tag me and I can try to come up with a minimum repro somewhere.
If this becomes the focus of implementation, I would really like to support it - as far as my skills are sufficient / needed.