Skip to content

Commit 22843fd

Browse files
lpssformspreeclaude
lpssformspree
and
claude
committed
Add comprehensive @formspree/react README and update @formspree/core with monorepo links
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent c3af88c commit 22843fd

2 files changed

Lines changed: 188 additions & 7 deletions

File tree

‎packages/formspree-core/README.md‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,12 @@
22

33
The core client library for [Formspree](https://formspree.io).
44

5-
## Releasing
5+
## Help and Support
66

7-
Run the following to publish a new version:
7+
For help and support please see the [Formspree docs](https://help.formspree.io).
88

9-
```
10-
npm run release
11-
```
9+
Part of the [formspree-js](https://github.com/formspree/formspree-js) monorepo. See also [`@formspree/react`](../formspree-react) and [`@formspree/ajax`](../formspree-ajax).
10+
11+
## License
12+
13+
MIT

‎packages/formspree-react/README.md‎

Lines changed: 181 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,186 @@
11
# Formspree React
22

3-
The React component library for [Formspree](https://formspree.io).
3+
React hooks and components for seamless form integration with [Formspree](https://formspree.io).
4+
5+
## Installation
6+
7+
Install with your preferred package manager:
8+
9+
```sh
10+
npm install @formspree/react
11+
# or
12+
yarn add @formspree/react
13+
# or
14+
pnpm add @formspree/react
15+
```
16+
17+
**Peer dependencies:** React 16.8, 17, 18, or 19.
18+
19+
_`@formspree/core` is included as a dependency, so you don't need to install it separately._
20+
21+
## Quick Start
22+
23+
```jsx
24+
import { useForm, ValidationError } from '@formspree/react';
25+
26+
function ContactForm() {
27+
const [state, submit, reset] = useForm('YOUR_FORM_ID');
28+
29+
if (state.succeeded) {
30+
return <p>Thanks for your submission!</p>;
31+
}
32+
33+
return (
34+
<form onSubmit={submit}>
35+
<label htmlFor="email">Email</label>
36+
<input id="email" name="email" type="email" />
37+
<ValidationError field="email" errors={state.errors} />
38+
39+
<label htmlFor="message">Message</label>
40+
<textarea id="message" name="message" />
41+
<ValidationError field="message" errors={state.errors} />
42+
43+
<ValidationError errors={state.errors} />
44+
45+
<button type="submit" disabled={state.submitting}>Send</button>
46+
</form>
47+
);
48+
}
49+
```
50+
51+
## `useForm`
52+
53+
The primary hook for form submissions.
54+
55+
```ts
56+
const [state, submit, reset] = useForm(formKey, options?);
57+
```
58+
59+
**Parameters:**
60+
61+
| Name | Type | Description |
62+
| --- | --- | --- |
63+
| `formKey` | `string` | Your Formspree form ID (required). |
64+
| `options.data` | `ExtraData` | Additional fields merged into every submission. |
65+
| `options.endpoint` | `string` | Custom API origin (default: `https://formspree.io`). |
66+
| `options.client` | `Client` | Custom Formspree client instance. |
67+
68+
**Returns a tuple:**
69+
70+
| Index | Name | Type | Description |
71+
| --- | --- | --- | --- |
72+
| 0 | `state` | object | Current form state (see below). |
73+
| 1 | `submit` | function | Submit handler — pass to `onSubmit` or call with data directly. |
74+
| 2 | `reset` | function | Resets all state back to initial values. |
75+
76+
**State properties:**
77+
78+
| Property | Type | Description |
79+
| --- | --- | --- |
80+
| `submitting` | `boolean` | `true` while the submission is in flight. |
81+
| `succeeded` | `boolean` | `true` if the last submission was successful. |
82+
| `errors` | `SubmissionError \| null` | Validation errors from Formspree, or `null`. |
83+
| `result` | `SubmissionSuccess \| null` | Success result with optional `next` redirect URL. |
84+
85+
## `useSubmit`
86+
87+
A lower-level hook that returns only a submit handler without managing state. Use this when you need full control over state management.
88+
89+
```ts
90+
import { useSubmit } from '@formspree/react';
91+
92+
const submit = useSubmit(formKey, options?);
93+
94+
// With a form event
95+
const handleSubmit = async (e) => {
96+
const result = await submit(e);
97+
// result is SubmissionSuccess or SubmissionError
98+
};
99+
100+
// Or with data directly
101+
const result = await submit({ email: 'user@example.com' });
102+
```
103+
104+
**Options:**
105+
106+
| Name | Type | Description |
107+
| --- | --- | --- |
108+
| `options.client` | `Client` | Custom Formspree client instance. |
109+
| `options.extraData` | `ExtraData` | Additional fields merged into every submission. |
110+
| `options.origin` | `string` | Custom API origin (default: `https://formspree.io`). |
111+
112+
## `ValidationError`
113+
114+
Renders validation error messages from a submission.
115+
116+
```jsx
117+
// Field-level errors
118+
<ValidationError field="email" errors={state.errors} />
119+
120+
// Form-level errors
121+
<ValidationError errors={state.errors} />
122+
123+
// With a prefix
124+
<ValidationError field="email" errors={state.errors} prefix="Email" />
125+
```
126+
127+
**Props:**
128+
129+
| Prop | Type | Description |
130+
| --- | --- | --- |
131+
| `errors` | `SubmissionError \| null` | The `errors` value from `useForm` state. |
132+
| `field` | `string` | Show errors for a specific field. Omit for form-level errors. |
133+
| `prefix` | `string` | Text prepended before each error message. |
134+
135+
Also accepts any standard `<div>` HTML attributes (e.g. `className`, `style`).
136+
137+
Renders nothing when there are no errors for the given field.
138+
139+
## `FormspreeProvider`
140+
141+
Optional context provider for sharing a Formspree client across your app and enabling Stripe payment integration.
142+
143+
```jsx
144+
import { FormspreeProvider } from '@formspree/react';
145+
146+
function App() {
147+
return (
148+
<FormspreeProvider project="YOUR_PROJECT_ID" stripePK="pk_test_...">
149+
<ContactForm />
150+
</FormspreeProvider>
151+
);
152+
}
153+
```
154+
155+
**Props:**
156+
157+
| Prop | Type | Description |
158+
| --- | --- | --- |
159+
| `project` | `string` | Formspree project ID. |
160+
| `stripePK` | `string` | Stripe publishable key — enables Stripe Elements for payment forms. |
161+
162+
When `stripePK` is provided, the provider wraps children in Stripe's `<Elements>` provider. Use the re-exported `CardElement` component for card inputs.
163+
164+
## Extra Data
165+
166+
Append additional fields to every submission using the `data` option. Values can be static strings, sync functions, or async functions. Return `undefined` to skip a field.
167+
168+
```jsx
169+
const [state, submit] = useForm('YOUR_FORM_ID', {
170+
data: {
171+
source: 'contact-page',
172+
referrer: () => document.referrer || undefined,
173+
sessionId: async () => await fetchSessionId(),
174+
},
175+
});
176+
```
4177

5178
## Help and Support
6179

7-
For help and support please see [the Formspree React docs](https://help.formspree.io/hc/en-us/articles/360055613373).
180+
For help and support please see the [Formspree docs](https://help.formspree.io).
181+
182+
Part of the [formspree-js](https://github.com/formspree/formspree-js) monorepo. See also [`@formspree/core`](../formspree-core) and [`@formspree/ajax`](../formspree-ajax).
183+
184+
## License
185+
186+
MIT

0 commit comments

Comments
 (0)