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">
      <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'