hapi-recaptcha-html

HAPI Form JS Library

A lightweight JavaScript library that integrates Alpine JS to enhance HAPI Forms with Google reCAPTCHA support and easy form submission handling.

Note: This library is intended for standard/static HTML websites (e.g., plain HTML/PHP templates). WordPress compatibility is not guaranteed due to theme/plugin script loading and optimization differences, and may require custom integration.

Usage

<!-- step 1) Load Hapi（provides Hapi.forms support） -->
<script src="https://unpkg.com/hapi-recaptcha-html@latest/dist/hapi.min.js" defer></script>
<!-- step 2) Register Hapi.forms(...) based on your configuration / setup -->
<script src="enquiry-forms.js" defer></script>

Usage Notes:

• Hapi.forms Initialization:
  Do not invoke Hapi.forms() inline immediately after loading external scripts with defer—this can result in a "Hapi is not defined" error if the script hasn’t finished loading.
  Best practice: Place your initialization code in a separate .js file and load it with defer, or ensure it executes after the DOM is fully loaded.
• Version Pinning:
  Avoid using @latest in CDN URLs. To ensure consistent behavior and prevent unexpected breaking changes, specify an explicit version. Example: <script src="https://unpkg.com/hapi-recaptcha-html@1.0.12/dist/hapi.min.js" defer></script>
• Alpine.js Management:
  This library automatically injects Alpine.js if not present.
  Important: Do not manually include multiple Alpine.js scripts on the same page to prevent conflicts.

DataLayer

DataLayer Integration

This library automatically pushes a form_submission event to the global window.dataLayer when a form is successfully submitted.

The event payload includes all form field values under the property enhanced_conversion_data.

Example pushed object:

{
  event: "form_submission",
  enhanced_conversion_data: {
    name: "John Doe",
    email: "john@example.com"
    // ...other fields
  }
}

You do not need to add any extra integration code for DataLayer support; it works out of the box.

Options

<script>
  Hapi.forms([
        // form 01
        {
          name: 'form01',
          hapiformID: '<hapiform-id-number-1>',
          redirectTo: '/contactus-success.html', // Eg: "/thank-you" or "https://example.com". (Optional)
          captchaId: 'captcha-01',
          integrationScriptUrl: "", // optional, POST current DataForm to external URL (API).
          recaptchaSize: "normal", //optional, normal or compact, default is normal
        },
        // form 02
        {
          name: 'form02',
          hapiformID: '<hapiform-id-number-2>',
          redirectTo: '/contactus-success.html',  // Eg: "/thank-you" or "https://example.com". (Optional)
          captchaId: 'captcha-02', 
          integrationScriptUrl: "", // optional, POST current DataForm to external URL (API).
          recaptchaSize: "normal", //optional, normal or compact, default is normal
        }
      ...
      ]
  );

</script>

Please note that you must use $store.<form-name>.fields.<field-name> to bind inputs.

<!-- in form01 -->
<input id="form01-name" x-model="$store.form01.fields.name">
...

<!-- in form02 -->
<input id="form02-name" x-model="$store.form02.fields.name">
...

• name: Alpine component name. Must match the form container x-data value (e.g. x-data="form01").
• hapiformID: HapiForm ID (UUID). Used to build the submit endpoint: https://hapiform.sg/api/{hapiformID}.
• redirectTo (optional): Redirect URL after a successful submission. Supports relative paths (e.g. /thank-you) and absolute URLs.
• integrationScriptUrl (optional): Webhook URL. When provided, the submitted payload will also be POSTed to this endpoint.
• captchaId (optional): DOM element id where reCAPTCHA will be rendered (e.g. <div id="captcha-01"></div>). Set to null to disable reCAPTCHA.
• recaptchaTheme (optional): light or dark. Default: light.
• recaptchaSize (optional): normal or compact. Default: normal.
• onSuccess(res) (optional): Callback invoked when the form submission succeeds.
• onFailed(err) (optional): Callback invoked when the submission or validation fails.
• errors.recaptchaError: Error message set when reCAPTCHA verification fails (bind to your UI for display).

Example

index.html

enquiry-forms.js

Test Case

index.html