useFormSubmit

A hook that provides access to the state and data of Forms on the page. This hook is a companion for Form and allows you to create fancy loading screens.

import { useFormSubmit } from 'next-runtime/form';

function MyPage() {
  const form = useFormSubmit('create-user');

  if (form.isLoading) {
    return <p>{`Currently submitting ${form.values.name}`}</p>;
  }

  return (
    <Form method="post" name="create-user">
      <input name="name" />
      <button type="submit">submit</button>
    </Form>
  );
}

#

Options

useFormSubmit takes the following options:

• name string

  The name of the form to connect to. As form names are optional, so is this option. That being said, we strongly recommend you to provide a name, as unnamed forms might cause issues in later stages of your project.

#

Returns

useFormSubmit returns an object holding the following properties:

• status string

  The status of this form. It will be one of the following options, and defaults to idle.

  • idle: if the form is at rest and hasn't yet been submitted.
  • submitting: the form is submitted, and waiting for response from the server. Form values are available under values and formData.
  • routing: the server returned a redirect, we're now rerouting the client.
  • error: the submission resulted in an error. Error details are stored under error.
  • success: the submission has been completed, and we got a response code in the 200 range, or have been redirected. Response data is stored under data.

• data: Record<string, unknown>

  The response data returned in case of a successful submission.

• error FetchError | Error

  In case of client side errors, this holds the standard Error type, with a name and message. In case of server-side errors, a FetchError is available. A FetchError extends the default Error class with the following properties:

  • message string- the error status code and message formatted as [status]: message
  • status number- the response status code
  • statusText string- the response status text
  • headers Headers- the response headers
  • data Record<string, unknown>- the response data

• formData FormData

  The form values that the user is submitting, provided as FormData.

• values Record<string, unknown>

  The form values that the user is submitting, provided in expanded form.

• isIdle Boolean

  A boolean status prop derived as status === 'idle'

• isSubmitting Boolean

  A boolean status prop derived as status === 'submitting'

• isRouting Boolean

  A boolean status prop derived as status === 'routing'

• isLoading Boolean

  A boolean status prop derived as status === 'loading' || status === 'routing

• isSuccess Boolean

  A boolean status prop derived as status === 'success

• isError Boolean

  A boolean status prop derived as status === 'error'