Form Component

[bluebill1049]

• Start Date: 02-02-2023

💁‍♂️ Summary

This proposal is made so we can discuss and find a proper and better developer experience to handle the form submission. Improve progress enhancement for existing form applications that are server-rendered eg NextJs.

👋🏻 Motivation

I am building a form builder application BEEKAI, during the development progress I found myself repeating the same code block for writing form submissions in multiple instances, including error handling and success handler. Over time, it creates inconsistency in the codebase, so I decided to build a Form component within the app to improve the following

• Developer expereience
• Leverage the standard web API
• Support progressive enhancement
• Works for 90% of the use case, and yet allows custom onSubmit callback
• Bring a great level of consistency to the codebase and reduce the repetitive code as below by establishing a good pattern

const { handleSubmit } = useForm();

const onSubmit = async (data) => {
  try {
    await fetch('/api', {
      headers: {
        "content-type": 'application/json',
      },
      body: JSON.stringify(data)
    })
    // error handling and status check
    // success handling
  } catch (e) {
    // error handling 
  }
}
<form onSubmit={handleSubmit(onSubmit)} />

📖 Design/Proposal

Introduce the new Form component, and here are some of the features I would like to cover:

• type-safe
• support progressive enhancement
  • ✅ Build-in validation will pass native constraint attribute to the inputs
  • ❌ Schema validation will not be covered in this PR since it requires external library support to serialise the schema attributes before the hook form can start setting up all the input attributes
• Inherit standard web API, eg action, method
• address the transformed output typescript issue: issue: can't get typescript to accept different schema output using zod #9600
• making sure this is optional

PR: #9735 (WIP)

The following is the full API design:

<Form<FormValues, TransformedFormValues>
  action="/api"
  method="post" // default to "post"
  onError={(payload: { response: Response, e: unknown }) => {}}
  onSuccess={payload: { response: Response }) => {}}
  validateStatus={(status: number) => {}}
  onSubmit={(data: FormValues) => {}}
  headers={{
    accessToken: 'accessToken'
  }}
  render={({ submit }) => { }} // headless version, so it would be compatible with React Native or you don't want to render form tag
/>

---

Default: Use case 1 (Post submission with FormData):

const { control } = useForm({
  // progressive: true, optional so it will not introduce a breaking change, we can consider default in the next major
})

<Form action="/api" control={control} />

The following code will be executed internally:

const formData = new FormData();
formData.append('xx', 'data)

await fetch('/api', {
  method: 'post',
  body: formData
})

---

Use case 2 (Post submission with JSON):

<Form
  action="/api"
  headers={{
    "content-type": 'application/json',
  }},
/>

The following code will be executed internally:

await fetch('/api', {
  headers: {
    "content-type": 'application/json',
  },
  body: JSON.stringify(data)
})

---

Use case 3 (Manual submission):

<Form 
  onSubmit={async (data) => {
    // or use mutation from SWR or Tanstack Query (React Query)
    await fetch('/api', {
      headers: {
        "content-type": 'application/json',
      },
      body: JSON.stringify(data)
    })
  }} 
/>

---

Use case 4 (React Native headless):

<Form action="/api/test" render={({ submit }) => {
  <Button onPress={submit}>Submit</Button>
}} />

---

Use case 5 (Remix, SWR, Tan Query):

// tan query or swr
<Form 
  action="/test"
  method="post"
  fetcher(({ data }) => mutation(data))
/>

// remix
const submit = useSubmit()
<Form 
  action="/test"
  method="post"
  fetcher(({ data, event }) => submit(event.currentTarget))
/>

😢 Drawbacks

• More abstraction and more decision-making for certain use cases
• Increase bundle size by a large percentage of 5% estimated, which means we will be close to 10KB

⛔️ Limitation

• progressive enhancement only applicable to the web with native build-in validation
• data transformation is not considered in the current scope

🙋‍♂️ Unresolved questions

Do we have any better approach or suggestions?

[paales]

This seems very specific to REST api's and doesn't seem to be handling responses? https://github.com/react-hook-form/react-hook-form/pull/9735/files#diff-3141588a73e90d115af4c8ba465ba5a776a5d401d6d460a49d8f58b1193173d9R51-R92

And in general this seems to a specific handler implementation. Might it be an idea to split this stuff up? The handler is where the magic is. We, for example are using apolloClient and we wouldn't be able to use this in the current form.

[bluebill1049]

Thanks for the feedback @paales it is probably not going to natively support Apollo and SWR/TanQuery, this feature is more aligned to web standards with form data and rests API. For apollo and server state library, the closed usage is Use case 3 (Manual submission):

[bluebill1049]

This seems very specific to REST api's and doesn't seem to be handling responses?

• validateStatus
• onSuccess
• onError

[nmanumr]

We also created something similar for our usecase internally. And we found following additions very useful for our use case:

• a global provider for onSubmit like swr global config which handles the form submission via axios
• an errors adoptor which transform the submission response to field errors if any also can be set globally
• transformData this prop transform data before submission. Needed this prop to form some hacks

[bluebill1049]

a global provider for onSubmit like swr global config which handles the form submission via axios

Yes, we can consider that after the initial release.

an errors adoptor which transform the submission response to field errors if any also can be set globally

can you share some examples?

transformData this prop transform data before submission. Needed this prop to form some hacks

Yes, we can consider supporting that as well.

[vladnicula]

I was going to mention error handling as well specifically the need to have a way to log API errors via Sentry and a way of handling logout redirects automatically. Axios is the lib of choice for my approach/style to handling forms, so if you have a clear way forward support for axios that would be great.

[bluebill1049]

We can go down that path later, once if the demand is high from the community.

[nmanumr]

For example this is an errors adaptor that transforms django restframework api errors into form errors. A basic drf error looks like this:

{“name”: [“field is required”]}

and the following errors adaptor transforms it to this respose to form field errors:

export function drfErrorsAdaptor(errors: ApiErrors) {
  function handleObject(err: ApiErrors) {
    const formErrors: FieldErrors = {};

    for (const [fieldName, error] of Object.entries(err)) {
      if (Array.isArray(error)) {
        if (typeof error[0] === 'string') {
          formErrors[fieldName] = {
            type: 'validate',
            types: (error as string[]).reduce((acc, el, i) => ({...acc, [`error${i}`]: el}), {}),
            message: error[0],
          };
        } else if (typeof error[0] === 'object') {
          formErrors[fieldName] = (error as ApiErrors[]).map((e) => handleObject(e)) as any;
        } else {
          // todo: maybe case case will never occur
        }
      } else if (typeof error === 'object') {
        formErrors[fieldName] = handleObject(error);
      } else if (typeof error === 'string') {
        formErrors[fieldName] = {
          type: 'validate',
          message: error,
        };
      }
    }

    return formErrors;
  }

  return handleObject(errors);
}

finally i would use it like this:

<Form
      action="/api/login"
      apiErrorAdaptor={drfErrorsAdaptor}
    >

infact in reality i would define this error adaptor only one in global form config provider and then i can override it if I want.

[bluebill1049]

Thanks for the example and it makes sense, I was wondering if we can achieve similar with the following

<Form
  onError={async ({ response, error }) => {
    drfErrorsAdaptor(error)
  }}
/>

[vladnicula]

I gave the new API a hypothetical go with a use case that I often deal with:

The current form version would look like this:

// outside the form, in a parent, mobx method maybe or similar code
const externalMethodThatDoesALotOfBusinessLogic = (validFormValues) => {
  // I only need to submit some keys. For example, there was a confirmPassword maybe 
  // in there and the server is in JAVA, written by a different company, and it crashes if I 
  // don't send over the exact payload they need. 
  const {username, password, ...leaveTheRestAlone } = validFormValues
  // call axiosInstance.post to a specific url, axios instances are preconfigured with a baseURL, some headers etc
  // full url might be someotherdomain.com/api/create. Logged out errors are handled inside the form, and inlcudes
  // an auth token or some additional headers not present in the form
  try {
    const response = mySpecificBackendInstance.post("/create", {username, password})
    if ( isOKBySomeBusinessLogic(response) ) {
      myRouterSolution.push("/some-path")
    } else {
      myFormRef.current.setFieldErrors(someWayOfMappingResponseDataToFieldErrors(response))
    }
  } catch (err) {
    logSentryError(err)
  }
}


// in the form
const { handleSubmit } = useForm();

return <form onSubmit={handleSubmit(props.externalMethodThatDoesALotOfBusinessLogic)} />

A rewrite with the new Form component would probably look like:

// outside the form, in a parent, mobx method maybe or similar code

// I'm handling success and maybe non server errors here?
const handleSuccess = (responseSuccess) => {
  // call axiosInstance.post to a specific url, axios instances are preconfigured with a baseURL, some headers etc
  // full url might be someotherdomain.com/api/create. Logged out errors are handled inside the form, and inlcudes
  // an auth token or some additional headers not present in the form
  try {
    if ( isOKBySomeBusinessLogic(response) ) {
      myRouterSolution.push("/some-path")
    } else {
      myFormRef.current.setFieldErrors(someWayOfMappingResponseDataToFieldErrors(response))
    }
  } catch (err) {
    logSentryError(err)
  }
}

const handleError = (response) => {
   myFormRef.current.showFormError("Maybe a generic message about something wrong on the server")
   logSentryError(err)
}

<Form
   // my form now only works with one endpoint, I need to add another prop for this to work
   // with a different endpoint. It also know knows about the server. Previously, it did not.
   // how do I strip some fields out of the payload?
   action="//someotherdomain.com/api/create"
   method="post" // default to "post"
   // I have not split my top down readable code that handles submissions, loading, error and success
   // into a ping pong between the handler code, the error code  and the RHF internal code
   onError={props.handleSubmissionError}
   // I actually kinda like onSuccess to be honest, not sure why, but having the router
   // redirect be passed like seems right.
   onSuccess={props.handleSuccess}
  // I'm not sure where my isOKBySomeBusinessLogic method would be called,
  // or how I would decide if a 200 STATUS code response with some key in the JSON response is actually 
  // an edge case. if I can't do this, it means again I need to know more than I did before in order to achieve 
  // the same result.
>

For me, since most of the forms that I work on have either one or more of this additional concerns, this new API is not very helpful, but not harmful at all.

However, for less experience developers, especially juniors / mids working in outsourcing companies (where I happen to teach this wonderful form library that I really love and I hope this feedback is not taken negatively :D ) this will be a gateway of writing code in a different way than other components that deal with API calls in their application, and a way of mixing error logging, headers and urls with a component that up until now worked perfectly in isolation.

[bluebill1049]

Thanks for the awesome feedback! Yes, abstraction will hide away the implementation detail and it's not 100% helping junior/mid-level developers, the same question goes for whether should you learn HTML/CSS or Javascript first (no right/wrong answer). It's optional, and having limited options sometimes it's not a bad thing. I think so far we have a large group of developers who is interested in such abstraction and also depends on what you are building and the requirement.

Developer learning path

Form component is an abstraction that we will not prompt as the first thing in the doc and definitely not before handleSubmit.

One of the big reasons

The important part is it's going to support progressive enhancement, which we have criticized.

Why not hook (not exactly your question)

Yes, it's possible to do a hook only. Component feels like the right tool for the right job before we further below up the configuration, especially considering everything we do in this component is optional.

When to use Form and when not

I think if your use case has the following feature, then Form at the moment is a NO for you

• I don't need progressive enhancement because I am not SSR
• I am using Graphql, SWR, Tanqueray and third-party levels doing the server fetch
• I need to preprocess my submission data

On the opposite you can do quite a lot with the Form Component include establish a good pattern:

const validateStatus = (status: number) => {
  return status === 200
}

const handleGenericRuntimError = (error: unknown) => {
  if (error.message === 'xxx') {
     // do A
  } else {
     // do B
  }
}

const handleRequestError = (response: Response) => {
  if (response.status === 400) {
     // do A
  } else {
     // do B
  }
}

const handleSuccess = (response: Response) => {
  // handle success
}

<Form 
  action="/api/test" // default to "post"
  validateStatus={validateStatus}
  onError={({ error, response }) => {
    handleGenericRuntimError(error)
    handleRequestError(response);
  }}
  onSuccess={({ response }) => {
    handleSuccess({ response })
  }}
/>

[vladnicula]

We are on the same page in this case :) If you mention the "When to use Form and when not" that would be amazing 👍

[bluebill1049]

Yes, will do.

[vladnicula]

Writing another coment with a different concern, regarding the Leverage the standard web API. Can you explain what you mean by this a bit more?

Right now, a form that uses register and the normal form should still work with a direct from submission, provided that the form tag has the method and url properties, no?

[bluebill1049]

<Form method="post" action="/api">
  <input {...register('test', { required: true })} />
</Form

// to

<form method="post" action="/api">
  <input name="test" required /> 
</form>

This then can be progressively enhanced with or without js

[vladnicula]

got it, I was thinking the same thing. Doesn't it work already?

<form onSubmit={handleSubmit(someMethod)} action='/api/something'/>

If JS is enabled it works with the RHF implementation, if not it submits to /api/something

[bluebill1049]

onSubmit will execute on submit and then be followed by the request, which behaviour the same native. you can still support your app without JS tho

const [mounted, setMounted] = useState(false)

useEffect(() => {
  !mounted && setMounted(true)
}, [setMounted])

<Form onSubmit={mutation} action={mounted ? '' : '/api/something'/}>

[bluebill1049]

Canary version: #9896

[bluebill1049]

Beta doc updated.

[AmitNeuhaus]

Hey @bluebill1049 so as i understand this syntax for declaring default values type and output values type isnt supported via useForm hook as you suggested ?

We have to use Form Component in order to achieve this?
Is there any other way using useForm hook to achieve nullable default values which are required in the output of the form via the resolver?

[bluebill1049]

We can add the same type of support for the hook, just the generic is getting a bit out of control.

[bluebill1049]

Just did. 9d41ff3

[AmitNeuhaus]

Amazing!!
Is this suppose to solve this case or it is just about schema transforming?

I didn't want to open an issue for that.
#9953 (comment)

[aspirisen]

Hello, looks like I didn't get if this Form component is supported in NextJS.
I tried to pass server action to action prop and it didn't work.
Will server actions will be supported by react-hook-form or I am doing smth wrong?