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. This sets up a project context for all forms in the app, and associates your forms with the keys specified in your formspree.json config file. Here's an example of using <FormspreeProvider> in a Next.js _app.js file:

import { FormspreeProvider } from '@formspree/react';
function App({ Component, pageProps }) {
  return (
    <FormspreeProvider project="{your-project-id}">
      <Component {...pageProps} />
    </FormspreeProvider>
  );
}
export default App;

If you don't use the CLI, you should put your form's hashid in place of the form key as the first argument to useForm.

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 either a form hashid obtained after creating a form in the Formspree dashboard, or a form key from 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:

Validations

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 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 (required)
• 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>

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:

data An Object containing Strings or Functions to merge with your form data.

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;
    }
  }
});