@boosterpack/react-form

React component + hook for Boosterpack Forms — invisible spam protection via Proof-of-Work (no CAPTCHA).

• Handles PoW + anti-spam hidden fields automatically
• Checks form status on mount and shows activation prompts when needed
• Submits directly to the Boosterpack Forms API (no embed.js needed)

Install

npm i @boosterpack/react-form

Usage (component)

'use client'

import { BoosterpackForm } from '@boosterpack/react-form'

export function ContactForm() {
  return (
    <BoosterpackForm formId="<FORM_ID>">
      {({ status, error }) => (
        <>
          <input name="name" placeholder="Name" required />
          <input name="email" type="email" placeholder="Email" required />
          <textarea name="message" placeholder="Message" required />

          <button type="submit" disabled={status === 'sending'}>
            {status === 'sending' ? 'Sending…' : 'Send'}
          </button>

          {status === 'success' && <p>Sent. Check your inbox.</p>}
          {status === 'error' && error && <p>{error}</p>}
        </>
      )}
    </BoosterpackForm>
  )
}

The component automatically checks form status on mount. If the form needs activation or the domain isn't allowed, a built-in overlay prompts the user (just like embed.js). Set showActivationOverlay={false} to handle this yourself.

Usage (hook)

'use client'

import { useBoosterpackForm } from '@boosterpack/react-form'

export function ContactForm() {
  const {
    status,
    error,
    formRef,
    handleSubmit,
    reset,
    formReady,
    activationStatus,
    requestActivation,
  } = useBoosterpackForm({
    formId: '<FORM_ID>',
    // serviceOrigin: 'http://localhost:3000', // optional for local/staging
  })

  return (
    <form ref={formRef} onSubmit={handleSubmit}>
      {formReady === 'not_activated' && (
        <div>
          <p>This form needs activation.</p>
          <button type="button" onClick={requestActivation}>
            {activationStatus === 'sent' ? 'Check your email' : 'Activate now'}
          </button>
        </div>
      )}

      {formReady === 'domain_not_allowed' && (
        <div>
          <p>This domain is not enabled yet.</p>
          <button type="button" onClick={requestActivation}>
            {activationStatus === 'sent' ? 'Check your email' : 'Enable domain'}
          </button>
        </div>
      )}

      <input name="name" placeholder="Name" required />
      <input name="email" type="email" placeholder="Email" required />
      <textarea name="message" placeholder="Message" required />

      <button type="submit" disabled={status === 'sending' || formReady !== 'ready'}>
        {status === 'sending' ? 'Sending…' : 'Send'}
      </button>

      {status === 'success' && (
        <button type="button" onClick={reset}>
          Send another
        </button>
      )}
      {status === 'error' && error && <p>{error}</p>}
    </form>
  )
}

Options

<BoosterpackForm> props

| Prop | Type | Default | Description | |------|------|---------|-------------| | formId | string | — | Your Boosterpack Forms form ID (UUID). Required. | | serviceOrigin | string | https://boosterpackforms.com | Override for self-hosted or staging. | | onSuccess | () => void | — | Called after a successful submission. | | onError | (error: string) => void | — | Called when submission fails. | | autoReset | boolean | false | Reset to idle after success. | | autoResetDelay | number | 3000 | Delay (ms) before auto-reset. | | autoCheckStatus | boolean | true | Check form status on mount. | | showActivationOverlay | boolean | true | Show built-in activation overlay. |

useBoosterpackForm return values

| Field | Type | Description | |-------|------|-------------| | status | FormStatus | 'idle' · 'sending' · 'success' · 'error' | | error | string \| null | Error message when status is 'error'. | | formRef | RefObject<HTMLFormElement> | Attach to your <form>. | | handleSubmit | (e: FormEvent) => void | Attach to onSubmit. | | reset | () => void | Reset back to idle. | | formReady | FormReadyState | 'checking' · 'ready' · 'not_activated' · 'domain_not_allowed' · 'disabled' · 'not_found' · 'error' | | activationStatus | ActivationStatus | 'idle' · 'sending' · 'sent' · 'rate_limited' · 'error' | | activationError | string \| null | Error from the last activation attempt. | | activationRetryAfter | number \| null | Seconds until rate limit resets. | | requestActivation | () => void | Send activation/domain-approval email. | | recheckStatus | () => void | Re-check form status from the server. |

Notes

• No file uploads: only text fields are supported.
• React peer deps: React 18+ and ReactDOM 18+.

License

MIT