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. This article assumes you're creating forms in the dashboard. For help with CLI projects, see our article on using the Formspree CLI.

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 hashid obtained by creating a form in the Formspree dashboard. 

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

Usage with Stripe

The Formspree React library includes support for payments via Stripe. The library handles most of the front end state management required to create payments and perform Strong Customer Authentication (SCA). The Formspree backend then takes care of submitting payments to Stripe. Together, Formspree dramatically reduces the development effort required to create a payment form.

Stripe functionality is lazy loaded. That means only a minimal stripe wrapper (just 6k compressed) is bundled with @formspree/react. The bulk of the Stripe library is loaded only if, and when, Stripe elements are first rendered.

To use Stripe, first wrap your app with the FormspreeProvider component and include the stripePK prop with your Stripe publishable key.

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

function MyApp() {
  return (
    <FormspreeProvider
      stripePK={'{your-stripe-publishable-key}'}
    >
      <PaymentForm />
    </FormspreeProvider>
  )
}

Then when building your form, use the CardElement component exported by @formspree/react. 

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

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

  if (state.succeeded) {
    return <div>Payment has been handled successfully!</div>;
  }

  return (
    <form onSubmit={handleSubmit}>
      <div>
        <label htmlFor="email">Email</label>
        <input id="email" type="email" name="email" />
      </div>
      <div>
        <label htmlFor="email">Card details</label>
        <CardElement />
        <ValidationError
          field="paymentMethod"
          errors={state.errors}
        />
      </div>
      <button type="submit" disabled={state.submitting}>
        {state.submitting ? 'Handling payment...' : 'Pay'}
      </button>
		</form>
  )
}

The CardElement component is passed-through directly from @stripe/react-stripe-js. It is exported by Formspree React only to ensure version consistency. The documentation for the CardElement component can be found here.

Note the field name "paymentMethod" on ValidationError. This is the field name used to send data from Stripe to Formspree, and must be passed to ValidationError to catch relevant Stripe errors.

Error codes

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