RFC: Form Context

[edmundhung]

RFC: Form Context

Status: Revised

Background

Conform utilizes the setCustomValidity() API and the invalid event to propagate the errors as a way to progressively enhancing the browser from validation. This has not been changed since the very first version: It keeps the validation result in the DOM and have each react hook watching their corresponding error state without relying on react context. (i.e. a data store).

If you are interested in how this works, check out my talk at Remix Conf. The implementation is different in Conform but the concept remains unchanged.

It sounds great, but...

• You can not set more than one message in an input with the setCustomValidity() API. If you have several errors, we need to concatenate them together. To support a more complex error structure, we might need to serialize it as well.
• You can not set a message to all input types. For example, browser ignores these API calls silently with hidden type input (i.e. <input type="hidden" />). Disabled or read-only inputs also suffer the same problem.
• Your validation result is not always tied to an input. How should we pass the form errors or the errors of a group of fields? (e.g. Errors of address as to errors of address.city)
• You need to have your dynamic input rendered first before you can set an error. You cannot set an error before the DOM is updated.

To get around these issues, Conform has to do some hacks, includes appending hidden buttons to your form and rendering your form twice. As it's hard to justify whether it worths relying on the browser APIs in the future, I have been experimenting a different approach based on store subscription with several changes in the APIs.

API Changes

The minimum react version required is now React 18.

Existing APIs: useForm, useFieldset and useFieldList

The useForm() hook is mostly the same:

import { useForm, getFormProps } from '@conform-to/react';

function Example() {
  const [form, fields] = useForm({
   // The options are mostly the same, except:
   // 1. Conform will generate an `id` for you with `useId()` if it is not provided
   // 2. `fallbackNative` is renamed to `defaultNoValidate`
  });

  // Instead of `form.props`, you will use a helper similar to the conform helpers:
  // They are all renamed to `getSomethingProps()` for clarity
  return (
    <form {...getFormProps(form)}>
      {/* ... */}
    </form>
  );
}

Both useFieldset() and useFieldList() hooks no longer exists as you can access the inner fieldset or fieldlist directly.

import { useForm, getInputProps } from '@conform-to/react';

function Example() {
  const [form, fields] = useForm({ ... });

  // Instead of `useFieldset(form.ref, fields.address)`, it is now:
  const address = fields.address.getFieldset();

  // Instead of `useFieldList(form.ref, fields.tasks)`, it is now:
  const tasks = fields.tasks.getFieldList();

  return (
    <form>
      <ul>
        {tasks.map((task) => {
          // It is no longer necessary to create an addtional fieldset component
          // As you can access the fieldset directly
          const taskFields = task.getFieldset();

          return (
            <li key={task.key}>
              <input {...getInputProps(taskFields.content)} />
              <input {...getInputProps(taskFields.completed)} />
            </li>
          );
        })}
      </ul>
    </form>
  );
}

You can still pass the metadata down to another component if you want:

import { type FieldMetadata } from '@conform-to/react';

function ExampleForm() {
  // ...

  return (
    <form>
      <AddressFieldset meta={fields.address} />
    </form>
  )
}

function AddressFieldset({ meta }: { meta: FieldMetadata<Address> }) {
  const address = meta.getFieldset();

  return (
    <fieldset>
      <input {...getInputProps(address.street)} />
      <input {...getInputProps(address.city)} />
    </fieldset>
  );
}

But there is now a better way to do it using a form context.

New APIs: FormProvider, useField and useFormMetadata

By setting up a react context with the <FormProvider />, we will now be able to subscribe to the form metadata using the useField() hook. This not only avoids prop drilling but also prevent unneccessary re-renders by tracking the usage of indivudal metadata through a proxy and only rerender it if the relevant metadata is changed.

The <FormProvider /> can also be nesteded with different form context and Conform will look up the closest form context unless a formId is provided.

import { type FieldName, FormProvider, useForm, useField } from '@conform-to/react';

function Example() {
  const [form, fields] = useForm({ ... });

  return (
    <FormProvider context={form.context}>
      <form>
        <AddressFieldset name={fields.address.name} />
      </form>
    </FormProvider>
  );
}

// The `FieldName<Schema>` type is basically a string with additional type information encoded
type AddressFieldsetProps = {
  name: FieldName<Address>
}

export function AddressFieldset({ name }: AddressFieldsetProps) {
  const [meta] = useField(name);
  const address = meta.getFieldset();

  // ...
}

If you want to create a custom input component, it is now possible too!

import { type FieldName, FormProvider, useForm, useField, getInputProps } from '@conform-to/react';

function Example() {
  const [form, fields] = useForm({ ... });

  return (
    <FormProvider context={form.context}>
      <form>
        <CustomInput name={fields.title.name} />
      </form>
    </FormProvider>
  );
}

type InputProps = {
  name: FieldName<string>
}

// Make your own custom input component!
function CustomInput({ name }: InputProps) {
  const [
    meta,
    form, // You can also access the form metadata directly
  ] = useField(name);

  return (
    <input {...getInputProps(meta)} />
  );
}

Similarly, you can access the form metadata on any component using the useFormMetadata() hook:

import { type FormId, FormProvider, useForm, getFormProps } from '@conform-to/react';

function Example() {
  const [form, fields] = useForm({ ... });

  return (
    <FormProvider context={form.context}>
      <CustomForm id={form.id}>
        {/* ... */}
      </CustomForm>
    </FormProvider>
  );
}

function CustomForm({ id, children }: { id: FormId; children: ReactNode }) {
  const form = useFormMetadata(id);

  return (
    <form {...getFormProps(form)}>
      {children}
    </form>
  );
}

FormMetadata & FieldMetadata

The form and field metadata now provide a wide range of information. In addition to the following properties that you might familiar with:

• id: An unique id for the field that could be used with label
• errorId: An unique id for the error message
• descriptionId: An unique id for the description element
• initialValue: The initial value of the field
• errors: An array of errors
• key: The key of the field

It now includes all these properties as well:

• value: The value of the field based on the FormData API
• valid: A shorthand for errors.length === 0
• dirty: A boolean by comparing the current value with the default value
• allErrors: An object including all errors within the fieldset, e.g. { 'address': [], 'address.city': [], 'address.street': [] }
• allValid: Similar to valid but checks all errors within the fieldset

[jaruesink]

<3 this is awesome, could have saved me many hours in my last project 😂

I would also love to see an example of how one input element could update the value of another input onChange using the context, if that's possible.

I wonder how hard it would be to just have one single provider across the whole app.

<GlobalFormProvider> could hold a function registerFormContext and then within the useForm hook you could have a useEffect that registers the context of the form by ID to the Global Form Provider?

I think the this would help form values be read or updated more easily from anywhere in the app as long as the form has been registered.

[edmundhung]

I would also love to see an example of how one input element could update the value of another input onChange using the context, if that's possible.

In case it was confusing: Conform does not own the value of the form. It's just syncing the value with the FormData API. So it won't be as straight-forward as an simple API to update the store value like others solution. But I do have an idea: Updating an input value by forcing react to re-mount an input using a key with a new default value. This can be done with a custom intent (e.g. reset intent) that takes a field name and an optional default value and update both the key and default value for you.

I don't have this implemented yet so I will share more when I test it out later.

<GlobalFormProvider> could hold a function registerFormContext and then within the useForm hook you could have a useEffect that registers the context of the form by ID to the Global Form Provider?

The main problem is exactly the useEffect. It means all subsequent hook calls will not receive the context value until the client is hydrated and breaks progressive enhancement. Having said that, I did managed to make a global context provider work at some point through a side effect during render without React complaining on the console. But it just doesn't feel right as this is what React tell us not to do with strict mode 😅

[jaruesink]

I sometimes forget that this is all very focused on progressive enhancement! Keep up the awesome work, I'll look forward to see how it evolves as it continues to gain traction.

[hauptrolle]

This looks very promising! 👍

Can you share an example how to use a custom input component, but make the name prop typesafe?

For example, we have this schema:

const schema = z.object({
  email: z.string().email(),
  password: z.string(),
  remember: z.boolean().optional(),
});

I want this to fail:

<CustomInput name="not-in-schema" formId={form.id} />

but this should be valid:

<CustomInput name="email" formId={form.id} />

[edmundhung]

What I mean type-safe is about the type of the field. Consider an number input like this:

interface NumberInputProps extends Field<number> {
   // ...
}

function NumberInput({ name, formId }: NumberInputProps) {
  const field = useField({ name, formId });

  return (
    <input {...conform.input(field, { type: number })} />
  );
}

Typescript will complain if you pass the name from the name field instead of the age field:

function ExampleForm() {
  const { form, fields } = useForm<{ name: string; age: number }>();

  return (
    <form>
       <NumberInput name={fields.name.name} formId={form.id}
    </form>
  );
}

This is done by encoding the type information into each field name through a type called FieldName<Schema> and your <NumberInput /> will warn because FieldName<string> does not satisfy FieldName<number>.

You are still allow to set a name manually like <NumberInput name="age" formId={form.id} /> but you are basically opting out from the type-safety. This is why you should continue using the name generated by Conform. You will set a name manually only when you have some special case in which your input is far from where you defined the form and you can't pass the name down.

[edmundhung]

Also, if you are using the generated name from Conform, then you will never have an invalid name. So the problem you are concerning won't be a case here.

[hauptrolle]

Ah, I see. Thanks for the explanation 👍

Another question from my side: Can you share an example of

• how to access a field value in a deep nested component?
• how to set a field value based on another field value? (For example: Disable a text field, when a checkbox is checked)

Thank you in advance 🙇

[confix]

Hi there! First of all: Thanks for the amazing work and your time. Seems to be moving into the right direction and those changes proposed might make it possible for us to fully transition to conform!

One quick question, tho. The onSubmit callback parameter for useForm seems to be missing at the experimental branch.

Is this change as intended and if yes, what would be the alternative way to intercept the form submission?

[edmundhung]

Thanks :) The onSubmit option is moved to the conform.form() helper.

[edmundhung]

I will move the onSubmit option back to the useForm to allow us colocating all form related logic in one place.

[ejoc]

This looks great <3
Could you share an example how to use requestIntent without ref? Would the formId be sent instead of the ref?

[edmundhung]

The requestIntent will be adjusted to accept a formId instead. But if you need to have access to the form element, you can also do document.forms.namedItem(formId)

[fiws]

Why is passing formId needed? Shouldn't this be redundant using the react context?

[edmundhung]

The formId is necessary in case you have a nested form context. I have also considered simplifying the case when there is only one form context found but there are two concerns:

1. You might have a form on the page already. If you want to add a new form at the layout level later on, you will need to also modify all the existing forms with the additional formId. This might looks surprising to many people.

2. Type safety. We have encoded some type information in the formId to ensure type safety. If we skip the formId, the useFormMetadata hook will now lost the type information.

[edmundhung]

I think you are right. I can continue requiring the formId with useFormMetadata but maybe we don't need FormId with useField at all. I just need to figure out a behaviour that make it least surprising. Thank you so much for the question!

[edmundhung]

Ok. I love this! I have updated the RFC and made the formId optional now in which Conform will look up the closest form context unless a formId is specified. Also with some minor tweak that makes the usages of each API consistent. Thanks again for pushing me to revisit this idea.

[fiws]

I have also explored how context could be used effectively with conform and ended up with this:

function Example() {
  const { FormContext, FormItem } = useConformForm({
    onValidate({ formData }) {
      return parse(formData, { schema });
    },
  });

  return (
    <FormContext>
      <form method="post">
        <FormItem name="name">
          <FormLabel>Name</FormLabel>
          <Input type="text" />
          <FormMessage />
        </FormItem>

        <FormItem name="city">
          <FormLabel>City</FormLabel>
          <Input type="text" />
          <FormMessage />
        </FormItem>

        <button>Submit</button>
      </form>
   </FormContext>
);

const FormLabel = ({ ...props }) => {
  const { id, name } = useField();

  if (!props.children) props.children = name;

  return <label htmlFor={id} {...props} />;
};
/* Implementation for Input & FormMessage would also be here */

How this would work

• FormContext is returned preconfigured so you don't need to wire it up (but there is a problem here … more on that later)

• FormContext also passes the form.props to it's child (behaves like asChild from radix) – so no wiring up needed there as well

• FormItem uses the name prop to provide a context of just a single form field (using the parent FormContext). This allows child components to just use useField without any arguments.

• FormItem also has it's props typed so only existing field names can be used ⭐
  image

• FormItem, Input and FormMessage would be custom components in this example. They use the useField hook which gets the context from the FormItem provider.

Possible implementation

This was cobbled together in a few hours, please be gentle 😅

Expand code

import { Slot } from "@radix-ui/react-slot";

const useConformForm = <
  Output extends Record<string, any>,
  Input extends Record<string, any> = Output
>(
  options: FormConfig<Output, Input>
) => {
  const [form, fieldset] = useForm<Output, Input>(options);

  const FormContext = ({ children }: { children: React.ReactNode }) => (
    <ConformContext.Provider value={{ form, fieldset }}>
      <Slot {...form.props} children={children} />
    </ConformContext.Provider>
  );

  return {
    FormContext,
    FormItem: FormItem<keyof Fieldset<Output>>,
    fieldset,
    form,
  } as const;
};

function FormItem<T extends string>({
  name,
  children,
}: {
  name: T;
  children: React.ReactNode;
}) {
  const field = useField(name);

  return (
    <FormItemContext.Provider value={{ field }} children={children} />
  );
}

const useField = (name?: string) => {
  const { fieldset } = React.useContext(ConformContext);
  const { field } = React.useContext(FormItemContext);

  if (name) return fieldset[name];
  if (field) return field;

  throw new Error("Need to specify a name or wrap in a FormItem");
};

Here is a full "working" example: https://codesandbox.io/p/sandbox/conform-context-example-1-4hcjq7?file=%2Fsrc%2FApp.tsx

The Problem

Returning the FormContext component like this in a hook causes the form to re-render unpredictably. This causes all input fields to clear on submit. I think this can be solved with useMemo, but I can't get it to work.

[fiws]

It's ok if you don't like this approach. But maybe you could help me fix my problem? 😅

[edmundhung]

Interesting! I thought you were building on top of the pre release version until I look into details how it is done. This reminds me the API from Tanstack Form which gives you a scoped form and field component.

I guess useMemo doesn't work here because Strict mode recreate the component even though it is supposed to memorize the result. Maybe you can try creating the component with useState and control it behaviour through a ref object.

I think the actual issue here is that form.props is not stable. If you put it as a dependency in the useMemo call, it will always recreate the form context 😅 Maybe you can mark each of the property on form.props as the dependency (But I also forgot whether the individual property is stable or not already)

[fiws]

I tried [] but then the form just never updates (duh). So i guess i have to pass in stuff that the form needs to update. But then we are back at the original problem. It always re-renders the whole form when the props change.

How does Tanstack solve this? 😄

[adaboese]

Has this been released?

[guelosuperstart]

Hello,

Thank you for your work and update !!!

I have a some questions/problems in my app with Remix/React

1. Before the update, in my action, I could set the error for a specific field like this:

submission.error.user = ['This account is already used'];

But now i have an error :

TS2339: Property error does not exist on type

2. i got this error but the code work

TS2339: Property value does not exist on type

const submission = parseWithZod(body, { schema:});
submission.value

3. in my component i got a warning i think

const data = useActionData<typeof action>();
  const [form, fields] = useForm({
    lastSubmission: data.submission, <----  TS2353: Object literal may only specify known properties, and lastSubmission does not exist in type
    onValidate({ formData }) {
      return parseWithZod(formData, { schema });
    },
    shouldRevalidate: 'onBlur',
  });

How can i fix it ?

Thank you so much

[edmundhung]

This looks really strange. Does it happens on all the forms you had? Or only on this page? What is the type of the submission object and submission.value when you mouse over it?

Here are a few things you can try:

• Restart the typescript language server / Just restart the whole IDE
• Reinstall all packages

[guelosuperstart]

HEllo,

export async function action({ request }: ActionFunctionArgs) {
const schema = intent === 'password' ? userUpdatePasswordFormSchema : profileUpdateInformationFormSchema;
const submission = parseWithZod(body, { schema });
 if (submission.status !== 'success') {
      return json({ result: submission.reply() });
    }

    await patchUser(String(currentUser?.uid), submission.value);

    if (intent === 'information' && credentials?.user) {
      credentials.user.firstname = submission?.value?.firstname ?? '';
      credentials.user.lastname = submission?.value?.lastname ?? '';
    }
}

[guelosuperstart]

Hello,

do you have an idea ^^?

[guelosuperstart]

Hello,
How are you,

I still have this "issue" :/

Do you have any idea ?

Thank you so much

[edmundhung]

It's likely because Typescript does not understand the relationship between schema and the intent. To solve this, a common solution is to utilize discriminated union.

With zod, it will look something like this:

const schema = z.discriminatedUnion('intent', [
  z.object({
    intent: z.literal('password'),
    // ...
  }),
  z.object({
    intent: z.literal('information'),
    // ...
  })
])

export async function action({ request }: ActionFunctionArgs) {
  const formData = await request.formData();
  const submission = parseWithZod(formData, { schema });

  if (submission.status !== 'success') {
    return json({ result: submission.reply() });
  }

  await patchUser(String(currentUser?.uid), submission.value);

  if (submission.value.intent === 'information' && credentials?.user) {
    credentials.user.firstname = submission.value.firstname ?? '';
    credentials.user.lastname = submission.value.lastname ?? '';
  }

  // ...
}

[aaronadamsCA]

@edmundhung, some early feedback on the excellent v1.0.0-rc.0 (hopefully you're okay with it here for now):

• The type option on getInputProps is now required.

  IMO you could just default to type: "text", to match the behaviour of the HTML element. Not a big deal either way, of course.

• It looks like InputProps["type"] is meant to omit all button types; if so, you should also remove "image" from the union.

• Please add undefined to FormOptions["lastResult"] for compatibility with TypeScript 'exactOptionalPropertyTypes`.

• Regarding the now-deleted sample code, the <InputComponent name={fieldset.name} /> followed by const [metadata] = useFieldset(name) pattern seemed unnecessarily complex. It took me a while to figure out I could just take <InputComponent metadata={fieldset} />. Maybe you had a point in demonstrating that bit of indirection, but I didn't quite understand the value of it.

[Pouet--]

Find out that when 2 operations on a list are sent one after each other, only 1 POST request is send to the server (I had to turn off client-side validation to find this).

Do you know if I have to queued the operations and wait for the "lastResult" object to come back before sending the next one ?

[edmundhung]

Hey @Pouet--, you can find a solution for the problem you have here #400. I have tagged you there but maybe GitHub didn't notify you.

[ivan-kleshnin]

The type option on getInputProps is now required.

But why it's required? Can't we just read the provided type from the DOM?

Feels excessive to write:

<TextInput {...getInputProps({type: "text"})}/>
<PasswordInput {...getInputProps({type: "password"})}/>

// <TextInput/> (assuming any UI library) resolves to <input type="text"/> by itself, etc.

[edmundhung]

As I shared at the beginning of this thread:

Yep. That was the reason why it was optional from the beginning. But I notice many people didn't realize that the type has an impact on how defaultValue / defaultChecked prop is derived and omitted the type option. I feel like it's better to enforce it then being missed out.

Conform prioritize Progressive enhancement and there is no way we can read the DOM value from the server. Also, I would suggest everyone to create their own getInputProps helpers since the one provided are designed for native element only and every project will have a slight different requirements depending on the UI library you are using.

[ivan-kleshnin]

Yep. That was the reason why it was optional from the beginning. But I notice many people didn't realize that the type has an impact on how defaultValue / defaultChecked prop is derived and omitted the type option. I feel like it's better to enforce it then being missed out.

Got your point. Thank you for the clarification 🙏 So I'll go with something like:

// utils.ts
export function splatInput<Schema>(metadata: FieldMetadata<Schema, any, any>, options: Omit<Parameters<GetInputProps>[1], "type"> = {}): ReturnType<typeof getInputProps> & {error?: string} {
  return {
    ...getInputProps(metadata, options as any), // "type" will be provided in JSX
    error: metadata.errors?.[0],
  }
}

export function splatTextarea(...) {
  ...
}