React Hook Form Lenses

Lenses in this library act as carriers for control and name information. They are designed to describe form structure and provide type-safe paths to nested data, rather than acting as containers for the data itself.

Key Principles

1. No Setters and Getters: The library does not provide methods to get or set values directly. This prevents bugs where developers might read a value from a lens expecting reactivity, which is not how React Hook Form operates. Always use standard React Hook Form hooks (like useWatch) to access reactive values.

2. Do Not Operate Values Directly: Avoid consuming raw values from the form state directly within components that rely on lenses. Because these values are not inherently reactive through the lens itself, components may fail to re-render. Instead, consume values via appropriate RHF hooks and pass them down as props.

3. Interop Pattern: Use .interop() to convert a lens into a format compatible with React Hook Form's internal APIs. For example, when using register, you can pass a callback to interop that receives the controller and the field name: lens.interop((ctrl, name) => ctrl.register(name)).

React Hook Form Lenses allows you to manage deeply nested form structures using composable lenses. You can use useLens to create a lens instance from a RHF control, then use methods like .focus() to drill into nested paths, .reflect() to transform shapes, and .interop() to bridge lenses with standard React Hook Form hooks like useFieldArray or register.

import { useForm } from 'react-hook-form';
import { Lens, useLens } from '@hookform/lenses';
import { useFieldArray } from '@hookform/lenses/rhf';

function FormComponent() {
  const { handleSubmit, control } = useForm<{
    firstName: string;
    lastName: string;
    children: {
      name: string;
      surname: string;
    }[];
  }>({});

  const lens = useLens({ control });

  return (
    <form onSubmit={handleSubmit(console.log)}>
      <PersonForm
        lens={lens.reflect(({ firstName, lastName }) => ({
          name: firstName,
          surname: lastName,
        }))}
      />
      <ChildForm lens={lens.focus('children')} />
      <input type="submit" />
    </form>
  );
}

function ChildForm({ lens }: { lens: Lens<{ name: string; surname: string }[]> }) {
  const { fields, append } = useFieldArray(lens.interop());

  return (
    <>
      <button type="button" onClick={() => append({ name: '', surname: '' })}>
        Add child
      </button>
      {lens.map(fields, (value, l) => (
        <PersonForm key={value.id} lens={l} />
      ))}
    </>
  );
}

function PersonForm({ lens }: { lens: Lens<{ name: string; surname: string }> }) {
  return (
    <div>
      <StringInput lens={lens.focus('name')} />
      <StringInput lens={lens.focus('surname')} />
    </div>
  );
}

function StringInput({ lens }: { lens: Lens<string> }) {
  return <input {...lens.interop((ctrl, name) => ctrl.register(name))} />;
}

The ArrayLens interface is used to manage and transform arrays within a form using lenses. It provides methods to focus on specific indices or paths, restructure array items via reflection, and map over array fields for rendering.

Key Methods:

• focus(path | index): Creates a new lens focused on a specific property path (e.g., '0.name') or a specific numeric index (e.g., 2).
• reflect(getter): Restructures array items. The getter function must return an array containing exactly one object where each field is a lens. This is useful for mapping complex nested structures to a flatter shape for components.
• map(fields, mapper): Iterates over the fields provided by useFieldArray and applies a mapper function to produce a new array of values.
• interop(): Returns a binding object containing getTransformer and setTransformer. This object must be passed to the useFieldArray hook from @hookform/lenses/rhf to bridge the lens logic with React Hook Form's field array state.

function Component({ lens }: { lens: Lens<{ items: { value: { inside: string } }[] }> }) {
  // Focus on the 'items' array and restructure it so each item has a 'data' field
  const transformedLens = lens.focus('items').reflect(({ value }) => [{
    data: value.focus('inside')
  }]);

  return <Items lens={transformedLens} />;
}

function Items({ lens }: { lens: Lens<{ data: string }[]> }) {
  // Use interop() to connect the lens to useFieldArray
  const { fields } = useFieldArray(lens.interop());

  return (
    <div>
      {lens.map(fields, (value, l) => (
        <div key={value.id}>
          {/* Focus the lens on the specific 'data' property of the current item */}
          <StringInput label="Value" lens={l.focus('data')} />
        </div>
      ))}
    </div>
  );
}

To use an ArrayLens with React Hook Form's field array functionality, you must call .interop() on the lens. This returns a LensInteropTransformerBinding which contains the necessary transformers to sync the lens-based state with the underlying form values. This binding should be passed directly to the useFieldArray hook provided by @hookform/lenses/rhf.

Note: Ensure you are importing useFieldArray from @hookform/lenses/rhf rather than the standard react-hook-form package when using this pattern.

import { useFieldArray } from '@hookform/lenses/rhf';

function MyComponent({ lens }: { lens: Lens<{ data: string }[]> }) {
  // Pass the result of interop() to useFieldArray
  const { fields } = useFieldArray(lens.interop());

  return (
    <div>
      {lens.map(fields, (value, l) => (
        <div key={value.id}>
          <input {...l.focus('data')} />
        </div>
      ))}
    </div>
  );
}