V8: Reusable components in TypeScript (using branded strings)

[felixschorer]

The Problem

Consider an app which has a model like this: An Address interface which is used by both the Person and Order interfaces.

interface Address {
  street: string
  houseNumber: number
  city: string
  country: string
}

interface Person {
  name: string
  address: Address
}

interface Order {
  item: string
  shippingAddress: Address
}

In Javascript we can easily create a generic AddressFields component for editing the address which can be either embedded in the PersonFields or the OrderFields component.

function AddressFields({ register, path }) {
  return <div>
    <input type="text" {...register(`${path}.street`)} />
    <input type="number" {...register(`${path}.houseNumber`)} />
    <input type="text" {...register(`${path}.city`)} />
    <input type="text" {...register(`${path}.country`)} />
  </div>
}

function PersonFields({ register }) {
  return <div>
    <input type="text" {...register('name')} />
    <AddressFields register={register} path="address" />
  </div>
}

function OrderFields({ register }) {
  return <div>
    <input type="text" {...register('item')} />
    <AddressFields register={register} path="shippingAddress" />
  </div>
}

In Typescript this is currently almost impossible (almost because it could be done with overloads or type assertions).

Branded strings to the rescue

In Typescript you can associate extra type information with a type using type assertions: Branded types.

We could use this technique to associate a path with the type of the form values and its resolved type. E.g.

type PathWithMeta<FormValues, Type> = string & { __formValues: FormValues, __type: Type }

We can then define basic functions for creating and joining such branded strings.

function of<FormValues, Key extends keyof FormValues>(key: Key) {
  return key as PathWithMeta<FieldValues, FieldValues[Key]>
}

function join<FieldValues, Type, Key extends keyof Type>(
  path: PathWithMeta<FieldValues, Type>, 
  key: Key,
) {
  return `${path}.${key}` as PathWithMeta<FieldValues, Type[Key]>
}

That would then allow us to use the same pattern which we've used in Javascript.

function AddressFields<FieldValues>(props: {
  register: UseFormRegister<FieldValues>, 
  path: PathWithMeta<FieldValues, Address>,
}) {
  const { register, path } = props
  return <div>
    <input type="text" {...register(join(path, 'street')} />
    <input type="number" {...register(join(path, 'houseNumber'))} />
    <input type="text" {...register(join(path, 'city'))} />
    <input type="text" {...register(join(path, 'country'))} />
  </div>
}

function PersonFields(props: { register: UseFormRegister<Person> }) {
  const { register } = props
  return <div>
    <input type="text" {...register('name')} />
    <AddressFields 
      register={register} 
      path={of<Person, "address">('address')} 
    />
  </div>
}

function OrderFields(props: { register: UseFormRegister<Order> }) {
  const { register } = props
  return <div>
    <input type="text" {...register('item')} />
    <AddressFields 
      register={register}
      path={of<Order, "shippingAddress">('shippingAddress')}
    />
  </div>
}

Required Changes

• The changes are mostly to the types. Every function which currently accepts path strings would need an overload to also accept PathWithMeta.
• Optionally, the functionality of of and join could be integrated into the functions directly.

  register(path, 'street')
  // or
  const registerAddress: UseFormRegister<Address> = register.for('address')
  registerAddress('street')

• useForm could also return a bound version of of which would make the type annotations obsolete.

Related issues

#5055
#7413

cc @kotarella1110 @jorisre @barrymay

[bluebill1049]

I love this RFC and this is a proper solution to address generic component type difficulty with of and join.

Optionally, the functionality of of and join could be integrated into the functions directly

How could we avoid breaking change? Ideally, I hope we can avoid changing/add register API, as this simple API is growing a little bit too fast over the years.

[felixschorer]

I am not a fan of that either. I am just listing some alternatives.

[felixschorer]

Actually, once all functions are converted to using LazyPath the path argument would be constrained to just string. PathWithMeta is a string. So we wouldn't even have to touch the overloads. It would just be a change to the types which work on paths. I.e. just PathValue.

So the entire feature would just be two functions, a new type PathWithMeta, and a conditional around PathValue.

type PathValue<T, P extends string> = 
  P extends PathWithMeta<T, infer U>
    ? U
    : PathValueImpl<T, P>;

[bluebill1049]

yea, that's it. I think by moveingFieldPath into string will make the generic component typing easier.

[felixschorer]

Yes, definitely.

[barrymay]

Would this be able to fit into the useFormContext model? Sounds like it would be a great fit.

[felixschorer]

Or just pass just pass the entire UseFormReturn down 😉

[felixschorer]

I mean the purpose of this feature is to enable strict type safety. That may require a bit more boilerplate code, but I am willing to pay that price.

[bluebill1049]

yep, 💯

[felixschorer]

To clarify, you can absolutely use it like that.

function AddressFields<FieldValues>(props: {
  path: PathWithMeta<FieldValues, Address>,
}) {
  const { path } = props
  const { register } = useFormConext<FieldValues>()
  return <div>
    <input type="text" {...register(join(path, 'street')} />
    <input type="number" {...register(join(path, 'houseNumber'))} />
    <input type="text" {...register(join(path, 'city'))} />
    <input type="text" {...register(join(path, 'country'))} />
  </div>
}

However, since useFormConext<FieldValues>() is basically useFormContext() as UseFormReturn<FieldValues>, you don't gain much type safety.

[barrymay]

Agreed that for fully strict type safety it may not work but with a more advanced custom hook there may be some options where you don't need to pass down the path prop, yet you can still get that useful register back from the hook. (The whole point of context for me is to avoid repetitive prop passing for complex scenarios)

[felixschorer]

The type arguments of of don't have to be specified, if one annotates the generic of AddressFields

function PersonFields(props: { register: UseFormRegister<Person> }) {
  const { register } = props
  return <div>
    <input type="text" {...register('name')} />
    <AddressFields<Person> 
      register={register} 
      path={of('address')} 
    />
  </div>
}

function OrderFields(props: { register: UseFormRegister<Order> }) {
  const { register } = props
  return <div>
    <input type="text" {...register('item')} />
    <AddressFields<Order> 
      register={register}
      path={of('shippingAddress')}
    />
  </div>
}

That even works when using LazyPath for the definition of of.

[bluebill1049]

nice!

[chrisb2244]

Is it possible to write a component that doesn't have to be nested? (Is there a 'root' path?)
I have something like your example, and it works well (using 8.0.0-alpha4), but if I want to use the without nesting it in or I can't find a way to pass path.

In my case, I have a Person I want to reuse, and it looks something like:

import ...
import { TextField, ... } from '@mui/material'

export type PersonProps = {
  firstName: string
  lastName: string
  email: string
}

export function Person<FieldValues>(props: {
  register: UseFormRegister<FieldValues>
  path: TypedFieldPath<FieldValues, PersonProps>
  defaultValue?: PersonProps
}) {
  const { register, path, defaultValue } = props
  return (
  <>
    <TextField {...register(join(path, 'firstName')), { required: true })} defaultValue={defaultValue?.firstName} />
    <TextField {...register(join(path, 'lastName')), { required: true })} defaultValue={defaultValue?.lastName} />
    <TextField {...register(join(path, 'email')), { required: true })} defaultValue={defaultValue?.email} />
  </>
  )
}

and when I use it like this it works fine:

type BiggerFormData = {
  firstPerson: PersonProps
  otherPeople: PersonProps[]
  ... other stuff ... 
}

// I couldn't make it work without an intermediate component to handle the array elements
const OtherPerson = <FieldValues,>(props: { 
  idx: number
  path: TypedFieldPath<FieldValues, PersonProps[]>
  register: UseFormRegister<FieldValues>
}) => {
  return <Person path={join(props.path, `${props.idx}`)} register={props.register} />
}

export const Blah = ({...}) => {
  const { register, control } = useForm<BiggerFormData>()
  const { fields, append, remove } = useFieldArray<BiggerFormData, 'otherPeople'>({ name: 'otherPeople', control })
  return (
    <>
      <Person<BiggerFormData> register={register} path={of('firstPerson')} />
       {fields?.map((p, idx) => {
         return <>
              <OtherPerson
                idx={idx}
                path={of<BiggerFormData, 'otherPeople', PersonProps[]>(
                  'otherPeople'
                )}
                register={register}
              />
              <Button onClick={() => remove(idx)}>Remove</Button>
            </>
          )
         <Button onClick={() => append({})}>Add Person</Button>
    </>
  )
}

But I can't find a way to not pass path to Person, like in

const { control, handleSubmit, reset, register } = useForm<PersonProps>({
    mode: 'onBlur'
  })
// What to put for path?
<Person<PersonProps> register={register} path={of('')} />

Undefined and null, or attempting to conditionally join ran into type errors every attempt (although probably I missed something obvious...)

One workaround would presumably be to in that component use

type WrappedPerson = { person: PersonProps }
...
const { register } = useForm<WrappedPerson >(...)
<Person<WrappedPerson > register={register} path={of('person')} />

but that seems a bit undesirable if it isn't required.

[felixschorer]

Thanks for bringing that up. That's something which I haven't considered yet.
There needs to be an empty path primitive.

You should be able to work around this like that:

function EMPTY<T>() {
  return '' as TypedFieldPath<T, T>
}

<Person<PersonProps> register={register} path={EMPTY()} />

[chrisb2244]

Thanks, that's a nice workaround! I'm still wrapping my head around the names for the generic types here.

[matamatanot]

ref #4739

[bluebill1049]

hey @matamatanot thanks for the input. Notice in the example

// which you still need to extends FormValues
const Input = <TFormValues extends IFormValues1 | IFormValues2>({

This new proposal is more flexible in terms of infer nested form.

If you refer to the following example, this AddressFields now can be placed inside any nested component.

function AddressFields<FieldValues>(props: {
  register: UseFormRegister<FieldValues>, 
  path: PathWithMeta<FieldValues, Address>,
}) {
  const { register, path } = props
  return <div>
    <input type="text" {...register(join(path, 'street')} />
    <input type="number" {...register(join(path, 'houseNumber'))} />
    <input type="text" {...register(join(path, 'city'))} />
    <input type="text" {...register(join(path, 'country'))} />
  </div>
}

<AddressFields path="bill" />
<AddressFields path="matamatanot" />

[arutkowski00]

Is it also going to work with control and useController ? I'd like to parametrize the convertDetails part of the name while keeping it type-safe, so the section can be reused for different fields with the same model.

export interface ConvertSectionProps {
  form: UseFormReturn<DealDetailsType>;
}

export function ConvertSection({
  form: { control, watch },
}: ConvertSectionProps) {
  const currency = watch("currencyCode");

  return (
    <ContentBlock>
      <AutoFormGrid>
        <InputField
          control={control}
          name="convertDetails.amount"
          label={`Amount (${currency})`}
        />
        <InputField
          control={control}
          name="convertDetails.maturityYears"
          label="Maturity (in years)"
        />
      </AutoFormGrid>
    </ContentBlock>
  );
}

Great proposal btw, can't wait for that to happen!

[felixschorer]

Yes, absolutely. You can give it a try already. There is an alpha version which implements #7389.

https://codesandbox.io/s/falling-cookies-s1xzb?file=/src/App.tsx

There are still some rough edges regarding NestedValue and UnpackNestedValue which requires type assertions for now. That should be finex in the final version.

[panrafal]

With some small help from lodash and type-fest I was able to solve it for v7 with this:

https://gist.github.com/panrafal/92e11be4401aee710d8616cf2b664c0d

It's fully type-safe and rather easy to use. I guess it should handle every bit of RHF as it's mostly some type magic.

type NestedValues = {
  foo: string
}
type Values = {
  nested: NestedValues
}

function FieldsToBeNested({form}: {form: NestedForm<NestedValues>> {
  const errors = form.get(form.formState.errors)
  return <div><input {...register(form.path('foo'))}/>{errors.foo?.message}</div>
}

function DirectForm() {
  const form = useForm<NestedValues>()
  return <FieldsToBeNested form={nestedForm(form)} />
}

function ComposedForm() {
  const form = useForm<Values>()
  return <FieldsToBeNested form={nestedForm(form, 'nested')} />
}

[jdpt0]

@panrafal This is great, thanks! Is it possible to get it working for optional nested form fragments? I'm currently getting errors when trying to pass a key that is potentially undefined.

[BrendanC23]

This looks really useful. Does anyone know how to modify it to handle TTransformedValues (a form schema that uses Zod transforms, and so has different input and output types?)

react-hook-form/src/useForm.ts

Line 49 in ed23a09

TTransformedValues extends FieldValues | undefined = undefined,

[BrendanC23]

I updated the types to be

export function nestedForm(
    form: UseFormReturn<any, any, any> | NestedForm<any>,
    path?: string | number,
): NestedForm<any>

which fixed the issue with TTransformedValues.

One other issue that I haven't been able to solve is how to handle a schema where the form has more props than the nested form needs. Using the example from the first post:

interface Address {
  street: string
  houseNumber: number
  city: string
  country: string
}

interface PersonAddress {
  street: string
  houseNumber: number
  city: string
  country: string
  personName: string
}

interface Person {
  name: string
  address: PersonAddress 
}

Here, Person has an extra personName field that isn't needed by the nested address component. This causes a type error if I use NestedForm.

[BrendanC23]

This solution also has an issue with FieldArray. It uses type-fest's Get type, which includes undefined in the return type by default. This can be fixed by changing the return type of nestedForm to

NestedForm<Get<TValues, TPath, { strict: false }>>;

As indicated by this issue, type-fest's Get also doesn't support a number type in the path (it returns unknown). So something like this doesn't work to handle forms with an array:

const index: number = 0;
const nested = nestedForm(form, `array.${index}.values`);

For now, the best workaround is

const index: number = 0;
const nested = nestedForm(form, `array.${index as 0}.values`);

[jdpt0]

Is there a way to get this working for more than a depth of one, either in V8 or V7? The solution provided by @panrafal works great for a nested form of one depth but doesn't work for a nested form within another nested form.

[cbejensen]

I don't love my current solution, but maybe it will spark some ideas? Just throwing it here in case it's helpful.

https://codesandbox.io/s/react-hook-form-watch-v7-ts-forked-b84nri?file=/src/PersonForm.tsx

[cbejensen]

We've started using this home-grown solution with useNestedForm instead: https://codesandbox.io/s/use-nested-form-v2-y13f33?file=/src/App.tsx

[dolma]

@cbejensen That's a neat solution, thanks! I've tried it and it does indeed solve the problem, however I'm running into some TS error in the getErrors function (in useNestedForm) and I'm not too sure how to fix it. I'll keep looking on my end but I wonder if you've encountered the same error (or similar) in your own project? And if so, how did you fix it?

[cbejensen]

It’s been awhile since I’ve even looked at this code. Don’t supposed you have a code sandbox or something I can look at?

[dolma]

Thanks for the quick reply! Sure yeah, here's a link to a TS playgroud with a repro: TS Playground

It's mostly just a copy paste of your code from the sandbox.

[cbejensen]

Sorry for the massive delay on this! I don't know why that error is appearing, but I would just cast it

[NixBiks]

I'm a bit confused on the state of this. Is this currently possible in v7? And is it "cancelled" in v8 due to this?

[Evgenyguzman]

Hi, any update on this? do we need to wait for v8 and are there any plans for v8 release?

[BrendanC23]

What is the current status of this? This PR looks like it does some of the implementation, but it was closed in June 2022.

[aspirisen]

It looks like similar to what I suggested some time ago #9289

[aspirisen]

Hi, I created a PR that demonstrates a Lens approach for building reusable components with TypeScript support #12284