The Formspree React library

Installation

This library assumes that React is already installed in your environment as a peer dependency. Our helpers rely on React Hooks, so you must be on version 16.8.0 or higher.

npm install @formspree/react

Source on GitHub | npm package

You can use this library with or without the Formspree CLI. If you use the CLI, you must place a <FormspreeProvider> in your top-level app or layout component. See our article on using the Formspree CLI.

If, instead of using the CLI, you create forms using the Formspree dashboard, you don't need to use <FormspreeProvider>. You should pass your form's hashid as the first argument to useForm instead of a form key. (see below) 

Usage

The useForm React hook is the easiest way to setup a React form with Formspree. Just import @formspree/react and then call useForm with the form's ID. The form ID is either a form hashid obtained by creating a form in the Formspree dashboard, or a form key that you chose when creating your formspree.json config file. 

import { useForm } from '@formspree/react';

function MyForm() {
  const [state, handleSubmit] = useForm('{your-form-id}');
  if (state.succeeded) {
    return <div>Thank you for signing up!</div>;
  }
  return (
    <form onSubmit={handleSubmit}>
      <label htmlFor="email">Email</label>
      <input id="email" type="email" name="email" />
      <button type="submit" disabled={state.submitting}>Sign up</button>
    </form>
  )
}

State object

The first value in the array returned by this hook is a state object:

const [state, handleSubmit] = useForm('{your-form-id}');

The state object contains the following properties:

State changes over time in the following ways:

• When handleSubmit is called, submitting becomes true
• If the submission fails server-side validations, errors is populated with the specific errors
• If the submission succeeds, succeeded becomes true
• After the submission request finishes, submitting always becomes false

errors Items in the errors array have the following properties:

Validation errors

Here's an example form using the ValidationError component to display field errors:

import { ValidationError, useForm } from '@formspree/react';

function MyForm() {
  const [state, handleSubmit] = useForm('{your-form-id}');
  if (state.succeeded) {
    return <div>Thank you for signing up!</div>;
  }
  return (
    <form onSubmit={handleSubmit}>
      <label htmlFor="email">Email</label>
      <input id="email" type="email" name="email" required />
      <ValidationError field="email" prefix="Email" errors={state.errors} />
      <button type="submit" disabled={state.submitting}>Sign up</button>
    </form>
  )
}

The ValidationError component accepts the following special properties:

• field — the name of the field for which to display errors. If no field attribute is provided then general (non field) errors will be reported. (See Error codes below)
• errors — the object containing validation errors (required)
• prefix — the human-friendly name of the field (optional, defaults to "This field")

All other props (such as className) are passed through to the <div> wrapper. If the given field is invalid, this component renders a <div> containing the error message:

<div {...props}>
  {prefix} {message}
</div>

Additional options

This hook accepts two arguments: the form key and an object containing options.

const [state, handleSubmit] = useForm('{your-form-key}', options);

Here are the acceptable options:

Usage Example

const [state, submit] = useForm('{your-form-id}', {
  data: {
    subject: 'Someone joined the newsletter',
    pageTitle: function() {
      // This function will be evaluated at submission time
      return document.title;
    }
  }
});

Error codes

The following error codes may appear in the state object's errors array: