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

The hooks in this library expect you to place the <FormspreeProvider> in your top-level app or layout component. Here's an example of a custom 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;

Usage

The useForm React hook is the easiest way to setup a React form with Formspree. First you must add a form in your formspree.json file and deploy it with the Formspree CLI. Then call useForm with the key you used in your config. 

import { useForm } from '@formspree/react';
function MyForm() {
  const [state, handleSubmit] = useForm('{your-form-key}');
  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-key}');

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-key}');
  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-key}', {
  data: {
    _subject: 'Someone joined the newsletter',
    pageTitle: function() {
      // This function will be evaluated at submission time
      return document.title;
    }
  }
});