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:
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, if applicable |
message |
A human-readable error message fragment (e.g. "is required") |
code |
A machine-friendly error code (See error codes below) |
properties |
An object containing various additional properties about the error |
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 nofield
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:
Key | Type | Description |
---|---|---|
data |
object | An Object containing strings or functions to merge with your form data |
client |
Formspree | An instance of the Formspree client |
debug |
boolean | Log debug statements for troubleshooting |
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:
Code | Field Error | Description |
---|---|---|
INACTIVE |
The form has been disabled | |
BLOCKED |
The form has been blocked | |
EMPTY |
No data was submitted | |
PROJECT_NOT_FOUND |
An invalid project key was used to submit the form | |
FORM_NOT_FOUND |
An invalid form hashid was used to submit the form | |
NO_FILE_UPLOADS |
File uploads are not supported for this form | |
TOO_MANY_FILES |
The form was submitted with too many file attachments | |
FILES_TOO_BIG |
One or more files uploaded exceeded the max file size | |
REQUIRED_FIELD_MISSING |
✓ | A field is required, but no value was provided |
REQUIRED_FIELD_EMPTY |
✓ | A field is required, but a blank or empty string was provided |
TYPE_EMAIL |
✓ | A field should contain an email |
TYPE_NUMERIC |
✓ | A field should contain a number |
TYPE_TEXT |
✓ | A field should contain text |