### Install @formspree/react

Source: https://help.formspree.io/articles/using-the-cli/build-a-mailchimp-form-with-react.md

Install the React helper library for Formspree in your project.

```bash
npm install @formspree/react
```

--------------------------------

### Install and Initialize Formspree CLI

Source: https://help.formspree.io/articles/using-the-cli/the-formspree-cli.md

Run these commands to install the Formspree CLI globally and initialize a new project. This creates an empty formspree.json file in the project root.

```shell
npm i -g @formspree/cli
formspree init
```

--------------------------------

### Example formspree.json Configuration

Source: https://help.formspree.io/articles/using-the-cli/the-formspree-cli.md

Example configuration for a newsletter sign-up form that adds subscribers to a Mailchimp list. The apiKey references an environment variable using $ notation.

```javascript
{
  "forms": {
    "signupForm": {
      "name": "Sign-Up Form",
      "actions": [{ 
        "app": "mailchimp", 
        "type": "addOrUpdateContact", 
        "apiKey": "$FORMSPREE_MAILCHIMP_APIKEY" 
      }]
    }
  }
}
```

--------------------------------

### Install Formspree CLI

Source: https://help.formspree.io/articles/using-the-cli/migrating-from-statickit-to-formspree.md

Install the Formspree CLI globally using npm.

```shell
npm i -g @formspree/cli
```

--------------------------------

### Install @formspree/ajax via npm or yarn

Source: https://help.formspree.io/articles/building-your-form/submit-forms-with-javascript-ajax.md

Use these commands to add the library to your project when using a bundler.

```bash
npm install @formspree/ajax   # via npm, or
yarn add @formspree/ajax      # via yarn
```

--------------------------------

### Example formspree.json file

Source: https://help.formspree.io/articles/using-the-cli/the-formspree-json-file.md

A complete example of a formspree.json file with a contact form, including captcha, fields, and an email action.

```javascript
{
  "forms": {
    "contact": {
      "name": "Contact Form",
      "captcha": {
        "type": "recaptcha",
        "recaptchaSecret": "my-secret"
      },
      "fields": {
        "email": { "type": "email", "required": true },
        "message": { "type": "text", "required": true }
      },
      "actions": [
        { "type": "email", "to": "john@example.com" }
      ]
    }
  }
}
```

--------------------------------

### formspree.json Airtable action example

Source: https://help.formspree.io/articles/using-the-cli/send-submissions-to-airtable.md

Example configuration for the Formspree CLI to send submissions to Airtable. Add this action to the formspree.json file. The apiKey references an environment variable $AIRTABLE_API_KEY. The syncSubmissions option is optional and defaults to false.

```json
{
    "forms": {
      "wedding": {
      "name": "Wedding presence confirmations",
      "actions": [
          {
          "app": "airtable",
          "type": "sendToTable", 
          "apiKey": "$AIRTABLE_API_KEY",
          "baseName": "Wedding",
          "tableName": "Confirmed guests",
          "syncSubmissions": true
        }
      ]
    }
  }
}
```

--------------------------------

### Sample Submissions Response

Source: https://help.formspree.io/articles/the-forms-api/form-submissions-api.md

Example JSON response showing the structure of the submissions data, including fields and submission objects.

```json
{
  "fields": [
    "_date", 
    "email", 
    "message",
    "_status"
  ], 
  "submissions": [
    {
      "_date": "2018-11-03T07:28:29.707632", 
      "email": "myemail@example.com", 
      "message": "asdfasdf",
      "_status": {
        "my@email.com": {
          "delivered": true,
          "processed": true,
          "dispatched": true
        },
        "plugin:discord": {
          "processed": true
        }
      }
    },
    ...
  ]
}
```

--------------------------------

### Fetch Submissions with cURL

Source: https://help.formspree.io/articles/the-forms-api/form-submissions-api.md

Example cURL command to fetch all submissions. Uses the API key as the username with an empty password.

```bash
curl -u :API_KEY https://formspree.io/api/0/forms/<hashid>/submissions
```

--------------------------------

### GitHub Actions deploy workflow

Source: https://help.formspree.io/articles/using-the-cli/the-formspree-cli.md

Example GitHub Actions step that sets environment variables from secrets and runs formspree deploy.

```yaml
steps:
  - shell: bash
    env: 
      - FORMSPREE_DEPLOY_KEY: ${{ secrets.FormspreeDeployKey }}
      - FORMSPREE_MAILCHIMP_APIKEY: ${{ secrets.MailchimpAPIKey }}
    run: formspree deploy
```

--------------------------------

### formspree.json configuration for Pipedrive create lead

Source: https://help.formspree.io/articles/using-the-cli/create-leads-in-pipedrive.md

Example configuration for the create lead action in formspree.json. The apiKey must be an environment variable reference. The value and currency fields are optional and only used when variableLeadValue is false.

```json
{
  "forms": {
    "salesForm": {
      "name": "Sales Form",
      "actions": [
        {
          "app": "pipedrive",
          "type": "createLead",
          "apiKey": "$apiKey",
          "overwriteContact": true
          "variableLeadValue": false,
          "value": 100,
          "currency": "EUR"
        }
      ]
    }
  }
}
```

--------------------------------

### Filter Submissions by Date

Source: https://help.formspree.io/articles/the-forms-api/form-submissions-api.md

Use the 'since' parameter to get submissions after a specific ISO date.

```bash
curl https://formspree.io/api/0/forms/<hashid>/submissions?since=2018-11-03T12:00:00
```

--------------------------------

### Wrap Next.js app with FormspreeProvider

Source: https://help.formspree.io/articles/using-the-cli/the-formspree-cli.md

Example of a top-level _app.js file in Next.js that wraps the app with FormspreeProvider, supplying the project ID obtained from the dashboard.

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

function App({ Component, pageProps }) {
  return (
    <FormspreeProvider project="YOUR_PROJECT_ID">
      <Component {...pageProps} />
    </FormspreeProvider>
  );
}
export default App;
```

--------------------------------

### Initialize useForm hook

Source: https://help.formspree.io/articles/using-the-cli/the-formspree-cli.md

Call useForm with the form key from formspree.json to get state and handleSubmit for form management.

```jsx
const [state, handleSubmit] = useForm('{form-key}');
```

--------------------------------

### Form component using useForm hook

Source: https://help.formspree.io/articles/using-the-cli/migrating-from-statickit-to-formspree.md

Example form component using the useForm hook from @formspree/react.

```jsx
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>
  )
}
```

--------------------------------

### Run a local web server with Python (Mac/Linux)

Source: https://help.formspree.io/articles/troubleshooting/unable-to-submit-form-error.md

Use this command to start a simple HTTP server on port 8000 when testing forms locally. This is necessary because opening HTML files directly via file:// does not send the referer header, causing the 'Unable to submit form' error.

```bash
python -m SimpleHTTPServer 8000
```

--------------------------------

### Example field rules configuration

Source: https://help.formspree.io/articles/using-the-cli/the-formspree-json-file.md

Shows a complete Formspree form configuration with field validation rules for email, birthdate, and document fields. Includes type, required, min, max, and contentType properties.

```javascript
{
  "forms": {
    "contact": {
      "name": "Contact Form",
      "fields": {
        "email": {
          "type": "email",
          "required": true
        },
        "birthdate": {
          "type": "datetime",
          "required": true,
          "min": "2002-09-21 13:13:00"        /* also accept dates */
        },
        "document": {
          "type": "file",
          "contentType": ["application/pdf"],  /* please use valid MIME Types */
          "min": 10                            /* MiB */
        }
      }
    }
  }
}
}
```

--------------------------------

### Webhook action configuration in formspree.json

Source: https://help.formspree.io/articles/using-the-cli/send-a-webhook.md

Configure a webhook action in the formspree.json file. The 'type' must be 'webhook' and 'url' is required. This example sends a POST request to http://example.com/hook.

```json
{
  "forms": {
    "contact": {
      "name": "Contact Form",
      "actions": [
        {
          "type": "webhook",
          "url": "http://example.com/hook"
        }
      ]
    }
  }
}
```

--------------------------------

### formspree.json configuration for Gorgias createSupportTicket

Source: https://help.formspree.io/articles/using-the-cli/create-support-tickets-in-gorgias.md

Example configuration for the formspree.json file that adds a create support ticket action for Gorgias. Requires the app to be 'gorgias', type 'createSupportTicket', and the apiKey must be a $env variable reference. The subdomain and email are also required.

```json
{
  "forms": {
    "support": {
      "name": "Support Form",
      "actions": [
        {
          "app": "gorgias",
          "type": "createSupportTicket",
          "apiKey": "$GORGIAS_APIKEY",
          "subdomain": "testformspree",
          "email": "test@formspree.io"
        }
      ]
    }
  }
}
```

--------------------------------

### JS Example: handleServerResponse with SCA

Source: https://help.formspree.io/articles/plugins/use-stripe-to-accept-payments-with-sca.md

Updates the handleServerResponse() function to catch required actions and resubmit the form. Uses Stripe's handleCardAction to open the 3DS modal and then resubmits with the resubmit key.

```javascript
function handleServerResponse(response) {
  if (response.error) {
    // Show error from server on payment form
    console.log(response.error);
  } else if (response && response.stripe.requiresAction) {
    // Stripe require additional actions to charge this card
    // Use Stripe.js to handle required card action and open 3DS
    stripe
      .handleCardAction(response.stripe.paymentIntentClientSecret)
      .then(function (stripeResult) {
        // TODO: implement this function to resubmit the form
        resubmitForm(stripeResult, response.resubmitKey);
      });
  } else {
    console.log("Payment finished successfully");
  }
}
```

--------------------------------

### formspree.json configuration for Freshdesk createSupportTicket

Source: https://help.formspree.io/articles/using-the-cli/create-support-tickets-in-freshdesk.md

Configuration example for the create support ticket action in formspree.json. Requires an apiKey as a $env variable reference and a subdomain without .freshdesk.com or https. The action implicitly validates that email is required and of type email, and that message or msg is required.

```javascript
{
  "forms": {
    "support": {
      "name": "Support Form",
      "actions": [
        {
          "app": "freshdesk",
          "type": "createSupportTicket",
          "apiKey": "$FRESHDESK_APIKEY"
          "subdomain": "newaccount1612001078242"
          
        }
      ]
    }
  }
}
```

--------------------------------

### JSON export example

Source: https://help.formspree.io/articles/form-and-project-settings/exporting-submissions.md

Shows the structure of a JSON export from Formspree, including email, fields, host, and submissions properties. Use this to understand the format when parsing exported data.

```javascript
{
    "email": [
        "team@formspree.io",
        "support@formspree.io"
    ],
    "fields": [
        "email",
        "message"
    ],
    "host": null,
    "submissions": [
        {
            "email": "emily@formspree.com",
            "message": "Formspree is awesome!"
        }
    ]
}
```

--------------------------------

### Script tag example with inline initialization

Source: https://help.formspree.io/articles/building-your-form/submit-forms-with-javascript-ajax.md

Complete HTML page using the script tag to load @formspree/ajax from unpkg and initialize the form with a global formspree function. The form ID must match the formElement selector.

```html
<div data-fs-success></div>
<div data-fs-error></div>

<form id="my-form">
  <label for="email">Email</label>
  <input type="email" id="email" name="email" data-fs-field />
  <span data-fs-error="email"></span>

  <label for="message">Message</label>
  <textarea id="message" name="message" data-fs-field></textarea>
  <span data-fs-error="message"></span>

  <button type="submit" data-fs-submit-btn>Submit</button>
</form>

<script>
  window.formspree =
    window.formspree ||
    function () {
      (formspree.q = formspree.q || []).push(arguments);
    };

  formspree('initForm', {
    formElement: '#my-form',
    formId: 'YOUR_FORM_ID',
  });
</script>
<script src="https://unpkg.com/@formspree/ajax@1" defer></script>
```

--------------------------------

### formspree.json configuration for Zendesk createSupportTicket action

Source: https://help.formspree.io/articles/using-the-cli/create-support-tickets-in-zendesk.md

Example configuration for the create support ticket action in formspree.json. Requires a Zendesk API token referenced via $ZENDESK_APITOKEN environment variable. The action implicitly adds an email validation rule.

```json
{
  "forms": {
    "support": {
      "name": "Support Form",
      "actions": [
        {
          "app": "zendesk",
          "type": "createSupportTicket",
          "subdomain": "formspree",
          "zendeskEmail": "zendesk@formspree.io",
          "apiToken": "$ZENDESK_APITOKEN"
        }
      ]
    }
  }
}
```

--------------------------------

### Custom field example

Source: https://help.formspree.io/articles/plugins/use-activecampaign-to-collect-contacts.md

Send custom field values by matching submission keys to ActiveCampaign custom field titles (case-insensitive, spaces ignored). This example matches a custom field titled "Company Size".

```html
<input type="text" name="companysize" placeholder="Company Size">
```

--------------------------------

### formspree.json configuration for Klaviyo subscribe profile

Source: https://help.formspree.io/articles/using-the-cli/add-subscribers-to-a-klaviyo-list.md

Example configuration for the subscribe profile action in formspree.json. The action requires the app key set to 'klaviyo', type 'addSubscriber', a listName, and an apiKey that must reference an environment variable. The defaultPhoneRegion is optional.

```json
{
  "forms": {
    "contact": {
      "name": "Contact Form",
      "actions": [
        {
          "app": "klaviyo",
          "type": "addSubscriber",
          "listName": "Newsletter",
          "defaultPhoneRegion": "US",
          "apiKey": "$KLAVIYO_API_KEY"
        }
      ]
    }
  }
}
```

--------------------------------

### formspree.json with Mailchimp action

Source: https://help.formspree.io/articles/using-the-cli/the-formspree-json-file.md

Example of a formspree.json file that configures a Mailchimp action for a contact form, using the addOrUpdateContact type and an API key from an environment variable.

```javascript
{
  "forms": {
    "contact": {
      "name": "Contact Form",
      "actions": [
        {
          "app": "mailchimp",
          "type": "addOrUpdateContact",
          "audience": "8djs8fg8d",
          "apiKey": "$MAILCHIMP_APIKEY"
        }
      ]
    }
  }
}
```

--------------------------------

### Form with reset button using useForm

Source: https://help.formspree.io/articles/working-with-react/the-formspree-react-library.md

Example form that uses the reset function to allow the user to submit again after a successful submission. It shows conditional rendering based on state.submitting and state.succeeded.

```jsx
function TestForm() {
    const [state, submit, reset] = useForm('{your-form-id}');

    if (state.submitting) {
        return <p>Submitting…</p>;
    }

    if (state.succeeded) {
        return (
            <div>
                <p>Thanks!</p>;<button onClick={reset}>Reset</button>
            </div>
        );
    }

    return (
        <div>
            <h1>Form</h1>
            <form onSubmit={submit}>
                <label htmlFor="email">Email</label>
                <input
                    id="email"
                    type="email"
                    name="email"
                    defaultValue="test@example.com"
                />

                <button type="submit">Sign up</button>

            </form>
        </div>
    );
}
```

--------------------------------

### HTML form with file upload

Source: https://help.formspree.io/articles/building-your-form/file-uploads.md

Set enctype="multipart/form-data" on the form and add an <input type="file"> to accept uploads. The example restricts accepted files to PNG and JPEG images via the accept attribute.

```html
<form method="POST" action="https://formspree.io/FORM_ID" enctype="multipart/form-data">
 <input type="email" name="email" placeholder="Your email">
 <textarea name="message" placeholder="Details of your problem"></textarea>
 <input type="file" name="attachment" accept="image/png, image/jpeg">
 <button type="submit">Send Test</button>
</form>
```

--------------------------------

### AJAX form submission with jQuery and reCAPTCHA v3

Source: https://help.formspree.io/articles/form-and-project-settings/using-recaptcha-v3.md

Submit a form using AJAX with jQuery and reCAPTCHA v3. The example shows how to execute reCAPTCHA and send the token to Formspree.

```html
<html>
<head>
    <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.5.1/jquery.min.js"></script>
    <script src="https://www.google.com/recaptcha/api.js?render={your-site-key}"></script>
</head>

<body>
    <button onclick="captcha()" class="btn btn-primary">click me</button>
    <script>
      function captcha() {
        grecaptcha.ready(function() {
          grecaptcha.execute('{your-site-key}', {action: 'submit'}).then(function(token) {
              $.ajax({
                url: "https://formspree.io/f/{your-form-id}",
                method: "POST",
                dataType: "json",
                data: {
                  email: "test@email.com",
                  message: "Hello world!",
                  "g-recaptcha-response": token
                },
                success: () => {
                  alert("Done!")
                },
                error: (err) => {
                  alert("Something wrong!", err)
                }
              });
          });
        });
      }
  </script>
<html>
```

--------------------------------

### Trello createCard action in formspree.json

Source: https://help.formspree.io/articles/using-the-cli/create-cards-in-trello.md

Example configuration for the Trello action in formspree.json. Requires an API Key and Server Token from the Trello Developer page. The action creates a card in the specified board and list.

```javascript
{
  "forms": {
    "sales-funnel": {
      "name": "Sales Funnel",
      "actions": [
        {
          "app": "trello",
          "type": "createCard", 
          "apiKey": "$TRELLO_API_KEY",
          "serverToken": "$TRELLO_SERVER_TOKEN",
          "boardName": "Sales",
          "listName": "leads"
        }
      ]
    }
  }
}
```

--------------------------------

### HTML input with duplicate name attribute

Source: https://help.formspree.io/articles/troubleshooting/i-m-receiving-an-invalid-replyto-email-error.md

First example of an input with name="email" that contributes to the duplicate-name error.

```html
<input type="text" name="email" id="email">
```

--------------------------------

### useForm with data option

Source: https://help.formspree.io/articles/working-with-react/the-formspree-react-library.md

Example of using the data option to merge custom data into the form submission. The pageTitle function is evaluated at submission time.

```jsx
const [state, handleSubmit, reset] = useForm('{your-form-id}', {
  data: {
    subject: 'Someone joined the newsletter',
    pageTitle: function() {
      // This function will be evaluated at submission time
      return document.title;
    }
  }
});
```

--------------------------------

### Example of resubmitting the form

Source: https://help.formspree.io/articles/plugins/use-stripe-to-accept-payments-with-sca.md

Shows how to resubmit the form to Formspree after Stripe SCA validation. Sends the payment intent ID and resubmit key in the request body.

```javascript
function resubmitForm(result, resubmitKey) {
  console.log("handle Stripe SCA result");
  if (result.error) {
    // Show error in payment form
    console.log("Stripe SCA error");
  } else {
    // The card action has been handled
    // The PaymentIntent can be confirmed again on the server
    fetch('https://formspree.io/f/', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ 
        paymentIntent: result.paymentIntent.id ,
        resubmitKey: resubmitKey,
        email: 'jenny@rosen.com',
      })
    }).then(function(result) {
      return result.json();
    }).then(handleServerResponse);
  }
}
```

--------------------------------

### Response body example for requires_action

Source: https://help.formspree.io/articles/plugins/use-stripe-to-accept-payments-with-sca.md

Shows the JSON response returned by Formspree when a payment requires SCA. Includes the resubmit key, payment intent ID, and client secret needed to continue.

```javascript
{
  "message": "requires_action",
  "resubmitKey": <key_generated_by_formspree>,
  "stripe": {
    "paymentIntentId": <id_from_the_payment_intent>,
    "paymentIntentClientSecret": <secret_generated_by_stripe>,
    "requiresAction": true
  }
}
```

--------------------------------

### formspree.json autoresponse configuration

Source: https://help.formspree.io/articles/using-the-cli/send-a-confirmation-email.md

Example configuration for the autoresponse action in formspree.json. It sets the action type to 'autoresponse' and defines the fromName, subject, and message for the confirmation email. The email field must be present in the form submission or Formspree will return an error.

```json
{
  "forms": {
    "support": {
      "name": "Request Form",
      "actions": [
        {
          "type": "autoresponse",
          "fromName": "Support Team",
          "subject": "Request received",
          "message": "We received your call! We'll get in touch soon."
        }
      ]
    }
  }
}
```

--------------------------------

### formspree.json configuration for googlesheets action

Source: https://help.formspree.io/articles/using-the-cli/send-submission-to-google-sheets-spreadsheet.md

Example configuration for the formspree.json file that sends form submissions to a Google Sheets spreadsheet. The privateKey should reference the private_key from the service account JSON file, and serviceAccount should be the client_email. The type must be sendToSpreadsheet. The sendInvitationTo field is optional and defaults to the form target email or account email.

```javascript
{
  "forms": {
    "support": {
      "name": "Clients Spreadsheet",
      "actions": [
        {
          "app": "googlesheets",
          "privateKey": "$GOOGLE_SHEETS_KEY",
          "serviceAccount": "formspree-test-service-account@formspree-test-account.iam.gserviceaccount.com",
          "type": "sendToSpreadsheet",
          "sendInvitationTo": "other@email.com"
        }
      ]
    }
  }
}
```

--------------------------------

### Custom field input example

Source: https://help.formspree.io/articles/plugins/use-mailerlite-to-create-subscribers.md

Add an input with a name matching a MailerLite custom field (e.g., 'company') to include that data in the subscriber. You can add as many fields as needed.

```html
<input type="text" name="company"/>
```

--------------------------------

### Use useForm hook in a React component

Source: https://help.formspree.io/articles/working-with-react/the-formspree-react-library.md

Import useForm from @formspree/react and call it with a form hashid. The hook returns state, handleSubmit, and reset. The example shows a success message and a form with email input and submit button.

```jsx
import { useForm } from '@formspree/react';

function MyForm() {
  const [state, handleSubmit, reset] = 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>
  )
}
```

--------------------------------

### HTML form with data attributes for ESM example

Source: https://help.formspree.io/articles/building-your-form/submit-forms-with-javascript-ajax.md

HTML form structure with data attributes (data-fs-success, data-fs-error, data-fs-field, data-fs-submit-btn) used by the ESM initialization. The form ID must match the formElement selector in the JavaScript.

```html
<div data-fs-success></div>
<div data-fs-error></div>

<form id="contact-form">
  <label for="email">Email</label>
  <input type="email" id="email" name="email" data-fs-field />
  <span data-fs-error="email"></span>

  <label for="message">Message</label>
  <textarea id="message" name="message" data-fs-field></textarea>
  <span data-fs-error="message"></span>

  <button type="submit" data-fs-submit-btn>Send</button>
</form>
```

--------------------------------

### Custom field input (date)

Source: https://help.formspree.io/articles/plugins/use-pipedrive-to-create-leads-and-contacts.md

Example of a custom field input. Use the exact custom field name as the input's name attribute. The value must match the field type (e.g., date).

```html
<input type="date" name="date">
```

--------------------------------

### Hubspot createContact action configuration in formspree.json

Source: https://help.formspree.io/articles/using-the-cli/create-leads-and-contacts-in-hubspot-using-the-formspree-cli.md

Example configuration for the hubspot action in formspree.json. It creates a contact using the createContact type and requires an accessToken from a private app. The leadStatus and lifeCycleStage fields are optional with defaults. overwriteContact controls whether to overwrite existing contacts.

```json
{
  "forms": {
    "registrationForm": {
      "name": "Registration Form",
      "actions": [
        {
          "app": "hubspot",
          "type": "createContact",
          "accessToken": "$accessToken",
          "leadStatus": "NEW",
          "lifeCycleStage": "lead",
          "overwriteContact": true
        }
      ]
    }
  }
}
```

--------------------------------

### AJAX form with Turnstile widget (Vanilla JS)

Source: https://help.formspree.io/articles/form-and-project-settings/protecting-your-forms-with-cloudflare-turnstile.md

Use this HTML example to submit a Formspree form via AJAX with the Turnstile widget automatically adding the hidden cf-turnstile-response input. The script prevents default submission, sends form data via fetch, and handles the JSON response.

```html
<!DOCTYPE html>
<html>
  <head>
    <title>Turnstile AJAX Demo</title>
    <!-- Turnstile script -->
    <script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>
  </head>
  <body>
    <form id="form" method="POST" action="https://formspree.io/f/<form-hashid>">
      <input type="email" name="email" placeholder="email@example.com" required />

      <!-- Turnstile widget (automatically adds hidden cf-turnstile-response input) -->
      <div class="cf-turnstile" data-sitekey="{site-key}"></div>

      <br />
      <button type="submit">Submit</button>
    </form>

    <script>
      const form = document.getElementById("form");

      form.addEventListener("submit", function (event) {
        event.preventDefault();

        // Grab all form fields, including the hidden cf-turnstile-response
        const data = new FormData(form);

        fetch(form.action, {
          method: form.method,
          body: data,
          headers: {
            "Accept": "application/json"
          }
        })
          .then(function (response) {
            return response.json();
          })
          .then(function (data) {
            console.log("Formspree response:", data);
          })
          .catch(function (error) {
            console.error("Error:", error);
          });
      });
    </script>
  </body>
</html>
```

--------------------------------

### AJAX form submission with hCaptcha and jQuery

Source: https://help.formspree.io/articles/form-and-project-settings/using-hcaptcha.md

Use this example to submit your form via AJAX with jQuery and hCaptcha. It includes the necessary script tags and the form with the hCaptcha widget. The JavaScript handles form submission and sends the hCaptcha response.

```html
<html>
  <head>
    <title>hCaptcha Demo</title>
    <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.5.1/jquery.min.js"></script>
    <script src="https://js.hcaptcha.com/1/api.js" async defer></script>
  </head>
  <body>
    <form id="form" method="POST">
      <input type="email" name="email" placeholder="email@example.com" />
      <div class="h-captcha" data-sitekey="{your-site-key}"></div>
      <br/>
      <input type="submit" value="Submit">
    </form>
    <script type="text/javascript">
      $("form").submit(function(e){
      e.preventDefault();
      var hcaptchaVal = $('textarea[name=h-captcha-response]').val();

      $.ajax({
        url: 'https://formspree.io/f/{your-form-id}',
        type: "POST",
        dataType: "json",
        data: {"h-captcha-response": hcaptchaVal, "email": $("input[name='email']").val()},
        success: function(data) {
          console.log(data)
        }
      })
     });
    </script>
  </body>
</html>
```

--------------------------------

### formspree.json configuration for MailerLite add subscriber

Source: https://help.formspree.io/articles/using-the-cli/add-subscribers-to-mailerlite.md

Example formspree.json configuration that adds a subscriber to MailerLite. The action requires an apiKey referencing an environment variable, and supports optional settings like groupName, resubscribe, autoresponders, subscriberStatus, and requireOptin.

```json
{
  "forms": {
    "contact": {
      "name": "Contact Form",
      "actions": [
        {
          "app": "mailerlite",
          "apiKey": "$MAILERLITE_API_KEY",
          "type": "addSubscriber",
          "groupName": "Formspree Test",
          "resubscribe": false,
          "autoresponders": false,
          "subscriberStatus": "active",
          "requireOptin": false
        }
      ]
    }
  }
}
```

--------------------------------

### Create .env.example template

Source: https://help.formspree.io/articles/using-the-cli/the-formspree-cli.md

Create a .env.example file with the deploy key variable name as a template for other developers.

```shell
echo "FORMSPREE_DEPLOY_KEY=" >> .env.example
```

--------------------------------

### Custom field select (single option)

Source: https://help.formspree.io/articles/plugins/use-pipedrive-to-create-leads-and-contacts.md

Example of a single-option custom field. The select name must match the custom field name, and each option's value must be a valid option name. Invalid options are ignored.

```html
<select name="Age">
  <option value="Above 18">Above 18</option>
  <option value="Under 18">Under 18</option>
</select>
```

--------------------------------

### Set up .env file

Source: https://help.formspree.io/articles/using-the-cli/the-formspree-cli.md

Create a .env file with the deploy key and add it to .gitignore to avoid committing secrets.

```shell
echo "FORMSPREE_DEPLOY_KEY=<your-deploy-key>" >> .env
echo ".env" >> .gitignore
```

--------------------------------

### AJAX form with Turnstile API explicit rendering

Source: https://help.formspree.io/articles/form-and-project-settings/protecting-your-forms-with-cloudflare-turnstile.md

Use this HTML example to render the Turnstile widget explicitly via the Turnstile API and handle the token manually in an AJAX submission. The script renders the widget on page load, sets the token in the form data, and resets the widget after submission.

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <script
    src="https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit"
    defer
  ></script>
</head>
<body>
  <form id="contact-form">
    <input type="email" name="email" placeholder="Email" required />
    <div id="turnstile-container"></div>
    <button type="submit">Send</button>
  </form>

  <script>
    let widgetId = null;

    // Render widget when the page finishes loading
    window.onload = function () {
      if (!window.turnstile) {
        console.error("Turnstile did not load.");
        return;
      }

      widgetId = window.turnstile.render("#turnstile-container", {
        sitekey: "{your-site-key}",
        callback: function (token) {
          console.log("Turnstile success:", token);
        }
      });
    };

    // AJAX submit
    document.getElementById("contact-form").addEventListener("submit", function (event) {
      event.preventDefault();
      const form = this;
      const formData = new FormData(form);

      // Ensure we send the token under the standard field name
      // If Turnstile already added a hidden input, this overwrites it.
      formData.set("cf-turnstile-response", token);

      fetch("/submit", {
        method: "POST",
        body: formData
      })
        .then((res) => {
          if (!res.ok) {
            throw new Error("Server error: " + res.status);
          }
          return res.text();
        })
        .then((text) => {
          alert("Server replied: " + text);
          // Reset for next submission
          window.turnstile.reset(widgetId);
          form.reset();
        })
        .catch((err) => {
          console.error(err);
          alert("Request failed: " + err.message);
        });
    });
  </script>
</body>
</html>
```

--------------------------------

### Initialize form with script tag

Source: https://help.formspree.io/articles/building-your-form/submit-forms-with-javascript-ajax.md

Use this snippet before the closing body tag if you are not using a bundler.

```html
<script>
  window.formspree =
    window.formspree ||
    function () {
      (formspree.q = formspree.q || []).push(arguments);
    };
  formspree(
    'initForm', 
    { formElement: '#contact-form', formId: 'YOUR_FORM_ID' }
  );
</script>
<script src="https://unpkg.com/@formspree/ajax@1" defer></script>
```

--------------------------------

### GET /api/0/forms/<hashid>/submissions

Source: https://help.formspree.io/articles/the-forms-api/form-submissions-api.md

Fetch all submissions for a form. Supports filtering via query parameters.

```APIDOC
## [GET] https://formspree.io/api/0/forms/<hashid>/submissions

### Description
Fetch all your submissions.

### Method
GET

### Endpoint
https://formspree.io/api/0/forms/<hashid>/submissions

### Parameters
#### Path Parameters
- **hashid** (string) - Required - The form's hashid.

#### Query Parameters
- **since** (string) - Optional - Get all submissions since a date. Dates must be ISO formatted, such as `2018-11-03T12:00:00`.
- **limit** (integer) - Optional - Limit the number of results.
- **offset** (integer) - Optional - Cursor in pagination. Frequently used in conjunction with limit.
- **order** (string) - Optional - Change the order. By default the order is `desc`.
- **spam** (boolean) - Optional - Return messages that have been flagged or marked as spam. By default this value is `false`.

### Request Example
```bash
curl -u :API_KEY https://formspree.io/api/0/forms/<hashid>/submissions
```

### Response
#### Success Response (200)
- **fields** (array of strings) - List of field names.
- **submissions** (array of objects) - List of submission objects.

#### Response Example
```json
{
  "fields": [
    "_date",
    "email",
    "message",
    "_status"
  ],
  "submissions": [
    {
      "_date": "2018-11-03T07:28:29.707632",
      "email": "myemail@example.com",
      "message": "asdfasdf",
      "_status": {
        "my@email.com": {
          "delivered": true,
          "processed": true,
          "dispatched": true
        },
        "plugin:discord": {
          "processed": true
        }
      }
    }
  ]
}
```
```

--------------------------------

### Before migration: StaticKitProvider in Next.js

Source: https://help.formspree.io/articles/using-the-cli/migrating-from-statickit-to-formspree.md

Original Next.js file using StaticKitProvider with a site prop.

```jsx
import { StaticKitProvider } from '@statickit/react';

function App({ Component, pageProps }) {
  return (
    <StaticKitProvider site="{your-site-id}">
      <Component {...pageProps} />
    </StaticKitProvider>
  );
}

export default App;
```

--------------------------------

### Get Submissions Endpoint

Source: https://help.formspree.io/articles/the-forms-api/form-submissions-api.md

Retrieves all form submissions. Requires an authenticated request with your API key and the form's hashid.

```http
GET https://formspree.io/api/0/forms/<hashid>/submissions
```

--------------------------------

### Initialize form with ESM

Source: https://help.formspree.io/articles/building-your-form/submit-forms-with-javascript-ajax.md

Import and initialize the form using the initForm function when working with a bundler.

```javascript
import { initForm } from '@formspree/ajax';

initForm({
  formElement: '#contact-form',
  formId: 'YOUR_FORM_ID',
});
```

--------------------------------

### Deploy Formspree Configuration

Source: https://help.formspree.io/articles/using-the-cli/build-a-mailchimp-form-with-react.md

Deploy your form configuration changes to Formspree using the CLI.

```bash
formspree deploy -k <your-deploy-key>
```

--------------------------------

### Form with ValidationError component

Source: https://help.formspree.io/articles/working-with-react/the-formspree-react-library.md

Example form using the ValidationError component to display field errors. It imports ValidationError and useForm from @formspree/react and shows a thank-you message on success.

```jsx
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>
  )
}
```

--------------------------------

### Paginate with Offset

Source: https://help.formspree.io/articles/the-forms-api/form-submissions-api.md

Use the 'offset' parameter as a cursor for pagination, often combined with limit.

```bash
curl https://formspree.io/api/0/forms/<hashid>/submissions?offset=10
```

--------------------------------

### CSS to hide reCAPTCHA response field

Source: https://help.formspree.io/articles/form-and-project-settings/adding-a-custom-recaptcha-v2-key.md

This CSS example visually hides the reCAPTCHA response field while keeping it accessible for validation. It uses absolute positioning and opacity to move it off-screen.

```css
/* CSS */
#g-recaptcha-response {
  display: block !important;
  position: absolute;
  margin: -50px 0 0 0 !important;
  z-index: -999999;
  opacity: 0;
}
```

--------------------------------

### After migration: FormspreeProvider in Next.js

Source: https://help.formspree.io/articles/using-the-cli/migrating-from-statickit-to-formspree.md

Updated Next.js file using FormspreeProvider with a project prop.

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

function App({ Component, pageProps }) {
  return (
    <FormspreeProvider project="{your-project-id}">
      <Component {...pageProps} />
    </FormspreeProvider>
  );
}

export default App;
```

--------------------------------

### HTML input with duplicate name attribute (second occurrence)

Source: https://help.formspree.io/articles/troubleshooting/i-m-receiving-an-invalid-replyto-email-error.md

Second example of an input with name="email" that also has id="phone", causing the duplicate-name error.

```html
<input type="text" name="email" id="phone">
```

--------------------------------

### Make reCAPTCHA field required with JavaScript

Source: https://help.formspree.io/articles/form-and-project-settings/adding-a-custom-recaptcha-v2-key.md

This JavaScript example sets the 'required' attribute on the reCAPTCHA response field when the page loads, enabling HTML5 validation. It targets the element with id 'g-recaptcha-response'.

```javascript
// javascript
window.onload = function() {
  var el = document.getElementById('g-recaptcha-response');
  if (el) {
    el.setAttribute('required', 'required');
  }
}
```

--------------------------------

### FormspreeProvider with Stripe publishable key

Source: https://help.formspree.io/articles/working-with-react/the-formspree-react-library.md

Wrap your app with FormspreeProvider and include the stripePK prop with your Stripe publishable key to enable Stripe payments.

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

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

--------------------------------

### useSubmit with react-hook-form

Source: https://help.formspree.io/articles/working-with-react/the-formspree-react-library.md

Use the useSubmit hook from @formspree/react to integrate Formspree with react-hook-form. The example shows how to handle form submission, map server-side errors to form fields, and display success or error messages.

```tsx
import { useSubmit } from '@formspree/react';
import { useForm } from 'react-hook-form';

type Inputs = {
  email: string;
  message: string;
  name: string;
};

export function WithReactHookForm() {
  const {
    formState: { errors, isSubmitSuccessful, isSubmitting },
    handleSubmit,
    register,
    setError,
  } = useForm<Inputs>();

  const submit = useSubmit<Inputs>(
    process.env.REACT_APP_REACT_HOOK_FORM_ID as string,
    {
      onError(errs) {
        const formErrs = errs.getFormErrors();
        for (const { code, message } of formErrs) {
          setError(`root.${code}`, {
            type: code,
            message,
          });
        }

        const fieldErrs = errs.getAllFieldErrors();
        for (const [field, errs] of fieldErrs) {
          setError(field, {
            message: errs.map((e) => e.message).join(', '),
          });
        }
      },
    }
  );

  return (
    <div>
      {isSubmitSuccessful ? (
        <h2>Your message has been sent successfully!</h2>
      ) : (
        <form onSubmit={handleSubmit(submit)}>
          <div className="block">
            <label htmlFor="email">Email</label>
            <input {...register('email')} id="email" type="email" />
            {errors.email && <p className="error">{errors.email.message}</p>}
          </div>
          <div className="block">
            <label htmlFor="name">Name</label>
            <input {...register('name')} id="name" />
            {errors.name && <p className="error">{errors.name.message}</p>}
          </div>
          <div className="block">
            <label htmlFor="message">Message</label>
            <textarea {...register('message')} id="message" rows={10} />
          </div>
          {errors.root && (
            <div className="block">
              <ul className="error">
                {Object.values(errors.root).map((err) => {
                  if (typeof err !== 'object') {
                    return <li key={err}>{err}</li>;
                  }
                  const { type, message } = err;
                  return <li key={type}>{message}</li>;
                })}
              </ul>
            </div>
          )}
          <button type="submit" disabled={isSubmitting}>
            {isSubmitting ? 'Submitting...' : 'Submit'}
          </button>
        </form>
      )}
    </div>
  );
}
```

--------------------------------

### Name input fields (firstName/lastName)

Source: https://help.formspree.io/articles/plugins/use-pipedrive-to-create-leads-and-contacts.md

Use firstName and lastName inputs to set the contact's name. If a user already exists with the given name, the lead is added under that account.

```html
<input type="text" name="firstName" placeholder="Your first name">
 <input type="text" name="lastName" placeholder="Your last name">
```

--------------------------------

### Configure ConvertKit opt-in form in formspree.json

Source: https://help.formspree.io/articles/using-the-cli/build-a-convertkit-form-with-react.md

Add an opt-in form with a ConvertKit applyTags action. The tags must already exist in your ConvertKit account.

```json
{
  "forms": {
    "optInForm": {
      "name": "Opt-In Form",
      "actions": [{ 
        "app": "convertkit", 
        "type": "applyTags",
        "tags": ["Newsletter"]
      }]
    }
  }
}
```

--------------------------------

### React signup form component

Source: https://help.formspree.io/articles/using-the-cli/the-formspree-cli.md

A complete React component using useForm to handle submission, show success message, and disable button while submitting.

```jsx
import { useForm } from '@formspree/react';

function SignupForm() {
  const [state, handleSubmit] = useForm('signupForm');
  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>
  )
}
```

--------------------------------

### Website input

Source: https://help.formspree.io/articles/plugins/use-hubspot-to-create-leads-and-contacts.md

Set the contact's website. Not required.

```html
<input type="url" name="website" placeholder="https://example.com">
```

--------------------------------

### CURL with Basic Auth

Source: https://help.formspree.io/articles/the-forms-api/api-authentication.md

Use this CURL command to make an authenticated request with Basic auth. Replace API_KEY with your master or public key.

```bash
curl -u :API_KEY https://some.domain/
```

--------------------------------

### Lifecycle callbacks in initForm

Source: https://help.formspree.io/articles/building-your-form/submit-forms-with-javascript-ajax.md

Hook into different stages of the submission lifecycle using onInit, onSubmit, onSuccess, onError, and onFailure callbacks. The context object contains the current form, endpoint details, client, and config object.

```javascript
initForm({
  formElement: '#contact-form',
  formId: 'YOUR_FORM_ID',

  // Called when the form is initialized
  onInit: (context) => {
    console.log('Form initialized');
  },

  // Called before submission is sent.
  onSubmit: (context) => {
    console.log('Submitting form');
  },

  // Called on successful submission.
  onSuccess: (context, result) => {
    console.log('Submission succeeded', result);
  },

  // Called if validation errors are received from Formspree
  onError: (context, error) => {
    console.log('Validation error', error);
  },

  // Called if unexpected errors are received (e.g., network failure).
  onFailure: (context, error) => {
    console.log('Unexpected error', error);
  },
});
```

--------------------------------

### Basic Authentication Header

Source: https://help.formspree.io/articles/the-forms-api/api-authentication.md

Use this header to authenticate with Basic auth. The password must be the master key or public API key; the username is ignored.

```http
Authorization: Basic base64_encoded(username:password)
```