Skip to content

Form

Form submission component with built-in state management.

</> Form: FormProps Since v7.44.0

Note: This component is currently in BETA

This component is optional and it takes care of the form submission by closely aligning with the standard native form.

By default, we will send a POST request with your form submission data as FormData. Set encType (or a Content-Type header via the headers prop) to application/json to send JSON instead.

  • Progressively enhancement for your form.
  • Support both React Web and React Native.
  • Take care of form submission handling.
<Form
  action="/api"
  method="post" // default to post
  onSubmit={() => {}} // function to be called before the request
  onSuccess={() => {}} // valid response
  onError={() => {}} // error response
  validateStatus={(status) => status >= 200} // validate status code
/>

Props

All props are optional

NameTypeDescriptionExample
controlControlcontrol object provided by invoking useForm. Optional when using FormProvider.
<Form control={control} />
actionstring | (formData: FormData) => unknownURL to submit to, or Since v7.84.0 a function (Server Action style) invoked with the submission's FormData.
<Form action={async (formData) => { 'use server'; await save(formData) }} />
method"post" | "put" | "delete"HTTP method used when action is a URL string. GET is not supported since submissions are sent as a request body. Defaults to post.
<Form method='post' />
encType"application/x-www-form-urlencoded" | "multipart/form-data" | "text/plain" | "application/json"Sets the request's Content-Type. By default the submission is sent as FormData; set this (or the headers prop) to application/json to send JSON instead.
<Form encType='application/json' />
childrenReact.ReactNodeForm contents.
<Form>{children}</Form>
renderFunctionRender prop function suitable for headless component.
<Form render={({ submit }) => <View/>} />
onSubmitFunctionFunction invoked after successful validation.
<Form onSubmit={({ data }) => mutation(data)} />
onSuccessFunctionFunction called after successful request to the server.
<Form onSuccess={({ response }) => {}} />
onErrorFunctionFunction called after failed request to the server.

setError function will be called to update errors state. root.server will be used as error key.
<Form onError={({ response }) => {}} />
headersRecord<string, string>Request headers object.
<Form headers={{ accessToken:  'xxx', 'Content-Type':  'application/json'  }} />
validateStatus(status: number) => booleanFunction to validate status code.
<Form validateStatus={status => status === 200} />
RULES

  • If you want to prepare or omit submission data, please use handleSubmit or onSubmit.

    const { handleSubmit, control } = useForm();
    const onSubmit =(data) => callback(prepareData(data))
    <form onSubmit={handleSubmit(onSubmit)} />
    // or
    <Form
      onSubmit={({ data }) => {
        console.log(data)
      }}
    />

  • Progressive Enhancement only applicable for SSR framework.

    const { handleSubmit, control } = useForm({
      progressive: true
    });
    

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

    // Renders
    

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

React Web

import { useForm, Form } from "react-hook-form"


function App() {
  const {
    control,
    register,
    formState: { isSubmitSuccessful, errors },
  } = useForm({
    // progressive: true, optional prop for progressive enhancement
  })


  return (
    <div>
      {/* Use action prop to make post submission with formData */}
      <Form
        action="/api"
        control={control}
        onSuccess={() => {
          alert("Success")
        }}
        onError={() => {
          alert("error")
        }}
      >
        <input {...register("name")} />
        {isSubmitSuccessful && <p>Form submit successful.</p>}
        {errors?.root?.server && <p>Form submit failed.</p>}
        <button>submit</button>
      </Form>
      {/* Manual form submission */}
      <Form
        onSubmit={async ({ formData, data, formDataJson, event }) => {
          await fetch("api", {
            method: "post",
            body: formData,
          })
        }}
      >
        <input {...register("test")} /> <button>submit</button>
      </Form>
    </div>
  )
}

React Native

import { useForm, Form } from "react-hook-form"
function App() {
  const {
    control,
    register,
    formState: { isSubmitSuccessful, errors },
  } = useForm()
  return (
    <Form
      action="/api"
      control={control}
      render={({ submit }) => (
        <View>
          {isSubmitSuccessful && <Text>Form submit successful.</Text>}


          {errors?.root?.server && <Text>Form submit failed.</Text>}
          <Button onPress={() => submit()} />
        </View>
      )}
    />
  )
}

Thank you for your support

If you find React Hook Form to be useful in your project, please consider starring and supporting it.

Edit