Subscribe to field changes outside react

[shkreios]

Prerequisites

This may be a purely over optimized solution just to reduce the number of react re-renders. It also uses undocumented and not simver following internal react-hook-form apis. So use it at your own risk.

Introduction

In my use case I have a large configurable invoicing editor for which I wanted to use react-hook-form on input side and @react-pdf/renderer for the live preview. Think of a split screen where the left side is the input form and the right side is a pdf preview. Since both pages need to calculate some additional properties from the inputs, such as net amount, tax, etc., and I already used zustand throughout the application, I wanted to synchronize react-hook-form with the zustand store. As I already moved the pdf generation into a web worker, to keep the typing experience lag free, I wanted to also minimize any unnecessary renders.

But now to the most important thing, this is what interfacing with this new hook looks like:

Installation

npm install react-hook-form-subscribe --save

Examples

• Open Basic example in CodeSandbox or StackBlitz
• Open RHF-Mui example in CodeSandbox or StackBlitz

Usage

...

const { control } = useForm({
    defaultValues: {
      firstname: "",
      lastname: "",
      amount: 0,
      dateRange: [new Date(), new Date()]
    }
  });

  // use the hook factory to create custom hook
  const useFormSubcribe = useCreateFormSubscribe(control);

  // subscribe to all changes to firstname
  useFormSubcribe("firstname", (firstname) => console.log(firstname));

  // subscribe to all changes to dateRange.0, dateRange.1 and amount
  useFormSubcribe(["dateRange", "amount"], ([dateRange, amount]) => {
    console.log(dateRange);
    console.log(amount);
  });

  // subscribe only to changes to dateRange.0
  useFormSubcribe("dateRange.0", (from, {name} ) => {
  console.log(from)
  console.log(name) // logs "dateRange.0"
  });

...

Features/Benefits

• Fields and payload are passed typesafe to the subscribe function
• Does not cause any react re-renders
• Subscribe function doesn't need to be wrapped in useCallback, but also doesn't resubscribe on each render with the help of useEvent

Use cases

• Syncing state react-hook-form state in real-time with any api
• Reactively updating other react-hook-form fields
• Syncing react-hook-form with other state libraries e.g. zustand
  Pretty much a imperative version of the useWatch hook

Implementation

startsWith.ts

export type StartsWith<T, b extends string> = T extends `${b}${infer f}` ? T : never;

export const startsWith = <T extends string, b extends string>(
  str: T,
  prefix: b
): str is StartsWith<T, b> => str.startsWith(prefix);

useFormSubscribe.ts

import { StartsWith, startsWith } from "./startsWith";
import { useCallback, useEffect, useMemo } from "react";
import type {
  Control,
  EventType,
  FieldPath,
  FieldPathValue,
  FieldPathValues,
  FieldValues
} from "react-hook-form";
import useEvent from "react-use-event-hook";

type UseFormSubscribeHook<TFieldValues extends FieldValues = FieldValues> = {
  <
    TFieldNames extends readonly FieldPath<TFieldValues>[],
    TCallback extends (
      value: FieldPathValues<TFieldValues, TFieldNames>,
      payload: {
        name?: StartsWith<FieldPath<TFieldValues>, TFieldNames[number]>;
        type?: EventType;
        values?: FieldValues;
      }
    ) => void
  >(
    names: readonly [...TFieldNames],
    callback: TCallback
  ): void;

  <
    TFieldName extends FieldPath<TFieldValues>,
    TCallback extends (
      value: FieldPathValue<TFieldValues, TFieldName>,
      payload: {
        name?: StartsWith<FieldPath<TFieldValues>, TFieldName>;
        type?: EventType;
        values?: FieldValues;
      }
    ) => void
  >(
    name: TFieldName,
    callback: TCallback
  ): void;
};

export const useCreateFormSubscribe = <
  TFieldValues extends FieldValues = FieldValues
>(
  control: Control<TFieldValues>
) => {
  const useFormSubscribe: UseFormSubscribeHook<TFieldValues> = useCallback(
    <
      TFieldNames extends readonly FieldPath<TFieldValues>[],
      TFieldName extends FieldPath<TFieldValues>,
      TCallback extends (
        value:
          | FieldPathValue<TFieldValues, TFieldName>
          | FieldPathValues<TFieldValues, TFieldNames>,
        payload: {
          name?:
            | StartsWith<FieldPath<TFieldValues>, TFieldName>
            | StartsWith<FieldPath<TFieldValues>, TFieldNames[number]>;
          type?: EventType;
          values?: FieldValues;
        }
      ) => void
    >(
      name: TFieldName | readonly [...TFieldNames],
      callback: TCallback
    ) => {
      const fn = useEvent(callback);

      const shouldSend = useMemo<(eventName: string) => boolean>(
        () => {
          if (name instanceof Array)
            return (eventName) => name.some((n) => startsWith(eventName, n));
          return (eventName) => startsWith(eventName, name);
        },
        // eslint-disable-next-line react-hooks/exhaustive-deps
        name instanceof Array ? name : [name]
      );

      useEffect(() => {
        return control._subjects.watch.subscribe({
          next: (payload) => {
            if (payload.name && shouldSend(payload.name)) {
              // @ts-expect-error
              fn(control._getWatch(name), payload);
            }
          }
        }).unsubscribe;
        // eslint-disable-next-line react-hooks/exhaustive-deps
      }, [control, fn, ...(name instanceof Array ? name : [name]), shouldSend]);
    },
    [control]
  );

  return useFormSubscribe;
};

Experimental tracked option

Instead of string paths, this option uses proxy objects to determine which field has been accessed and thus needs to be subscribed to.

CAUTION the current proxy implementation calls the subscribe function for the first time if any fields changes and only track the accessed properties in this first call and subsequent calls will not be tracked

...

const { control } = useForm({
    defaultValues: {
      firstname: "",
      lastname: "",
      amount: 0,
      dateRange: [new Date(), new Date()]
    }
  });

  const useFormSubcribe = useCreateTrackedSubscribe(control);

  useFormSubcribe(({firstname}) => console.log(firstname));

  useFormSubcribe(({dateRange, amount}) => {
    console.log(dateRange);
    console.log(amount);
  });

  useFormSubcribe(({dateRange: [from]}, {name} ) => {
  console.log(from)
  console.log(name) // logs "dateRange.0"
  })
...

Experimental tracked implementation

import { useCallback, useEffect, useRef } from "react";
import { Control, EventType, FieldValues } from "react-hook-form";
import useEvent from "react-use-event-hook";

const getProto = Object.getPrototypeOf;

const isObject = <T>(obj: T): obj is T extends object ? T : never =>
  obj &&
  typeof obj === "object" &&
  (getProto(obj) === Object.prototype || getProto(obj) === Array.prototype);

function remove<T>(array: T[], element: T): void {
  const index = array.indexOf(element);
  if (index !== -1) {
    array.splice(index, 1);
  }
}

function createProxy<T extends object>(
  parentPath: string,
  fields: string[],
  obj: T
): T {
  return new Proxy(obj, {
    get(target, prop, receiver) {
      const val = Reflect.get(target, prop, receiver);
      if (Array.isArray(obj) && isNaN((prop as unknown) as number)) {
        return val;
      }

      const fullPropName = parentPath
        ? `${parentPath}.${prop.toString()}`
        : prop.toString();

      if (!fields.includes(fullPropName)) {
        remove(fields, parentPath);
        fields.push(fullPropName);
      }

      if (isObject(val)) return createProxy(fullPropName, fields, val);
      return val;
    }
  }) as T;
}

const getValues = <TFieldValues extends FieldValues = FieldValues>(
  control: Control<TFieldValues>
) => ({
  ...control._defaultValues,
  ...(control._stateFlags.mount ? control._formValues : {})
});


export const useCreateTrackedSubscribe = <
  TFieldValues extends FieldValues = FieldValues
>(
  control: Control<TFieldValues>
) =>
  useCallback(
    <
      TCallback extends (
        value: TFieldValues,
        payload: {
          name?: string;
          type?: EventType;
          values?: FieldValues;
        }
      ) => void
    >(
      callback: TCallback
    ) => {
      const stableCallback = useEvent(callback);

      const fields = useRef<string[] | undefined>(undefined);

      const fn = useCallback<TCallback>(
        // @ts-ignore
        (value, payload) => {
          if (fields.current) {
            return stableCallback(value, payload);
          }
          fields.current = [];
          return stableCallback(
            createProxy("", fields.current, value),
            payload
          );
        },
        [stableCallback]
      );

      useEffect(() => {
        return control._subjects.watch.subscribe({
          next: (payload) => {
            if (
              payload.name &&
              (!fields.current || fields.current?.includes(payload.name))
            ) {
              // @ts-ignore
              fn(getValues(control), payload);
            }
          }
        }).unsubscribe;
        // eslint-disable-next-line react-hooks/exhaustive-deps
      }, [control, fn]);
    },
    [control]
  );

Would love to here some feedback
Thanks have a great day 🙂

[bluebill1049]

Thanks for sharing such a solution!

[shkreios]

Do you plan to include a similar api/hook inside react-hook-form in future?
I saw this issue which was closed some time ago.
For now i created a library out of the code from this discussion react-hook-form-subscribe.

[bluebill1049]

We can consider having such an API in the future, but it's not the priority right now.

[bluebill1049]

Some ideas for API:

• subscription without render

const { getFormState } = useForm()

getFormState(); // return current form state 

getFormState({
  dirtyFields: true,
  name: 'test'
}).subscribe((formState) => {
  console.log(formState)
})

• external subscription

import { createFormControl } from '@hookform/core'

const formControl = createFormControl();

formControl.getFormState().subscribe()

function Test() {
  const { formstate } = useForm({
     control: formControl,
  })
  return null;
}

[shkreios]

If I understand your proposal correctly the API inside a react component should look like this correct?

const App: FC = () => {
const { getFormState } = useForm()

useEffect(() => 
  getFormState({
    dirtyFields: true,
    name: 'test'
  }).subscribe((formState) => {
    console.log(formState)
  }) // returning unsubscribe as cleanup function
},
[getFormState])

return <form>...</form>
}

or would the useWatch hook be extended to have the similar api as watch currently has, i.e.

watch((data, { name, type }) => console.log(data, name, type))
useWatch({
    control,
    name,// string | string[]
   subscribe: (data, { name, type }) => console.log(data, name, type) 
});

[shkreios]

Maybe we can link this discussion in the issue I mentioned to gather feedback on whether people need such an API. Unfortunately, I can't do that since it's locked for non-contributors.
Or is the normal procedure to directly open an RFC discussion?

[bluebill1049]

Or is the normal procedure to directly open an RFC discussion?

It's a normal discussion and select type RFC, once it's out I can ping that in the discussion panel. If you are interested, you can work on the PR as well.

[bluebill1049]

If I understand your proposal correctly the API inside a react component should look like this correct?

Yes.

[andrewcoelho]

@bluebill1049 would you still be interested in getting this sort of api added to react-hook-form? I'm unclear on the status of the migration to the framework agnostic @hookform/core package which seems like it would solve a similar problem, namely having access to formControl outside of react.