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:
Key | Description |
---|---|
submitting |
A Boolean indicating whether the form is currently submitting (defaults to false ) |
succeeded |
A Boolean indicating whether the form successfully submitted (defaults to false ) |
errors |
An Array of server-side validation errors (defaults to [] ) |
State changes over time in the following ways:
- When
handleSubmit
is called,submitting
becomestrue
- If the submission fails server-side validations,
errors
is populated with the specific errors - If the submission succeeds,
succeeded
becomestrue
- After the submission request finishes,
submitting
always becomesfalse
errors
Items in the errors
array have the following properties:
Key | Description |
---|---|
field |
The name of the field |
message |
A human-readable error message fragment (e.g. "is required") |
code |
A machine-friendly error code (e.g. "REQUIRED" or "EMAIL_FORMAT") |
properties |
An object containing various additional properties about the error |
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:
Key | Type | Description |
---|---|---|
data |
object | An object containing additional form fields to send |
client |
Formspree | An instance of the Formspree client |
debug |
boolean | Log debug statements for troubleshooting |
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;
}
}
});