Skip to content

Basin JS (v2)

v1 docs

The easiest way to add spam protection and redirect or render alerts on your forms

Why Basin JS?

  1. Allow customers to submit multiple forms without leaving the page
  2. Protect your form submission data from spam
  3. No code required

Basin JS automates the process by:

  1. Submitting your form to Basin via AJAX

  2. Displaying a success div or redirecting after the form has been submitted and displaying an error div if submission fails. It supports Webflow\'s native form interactions (success and error messages) out of the box.

  3. Adding an invisible captcha of your choice to prevent spam:

    • ReCAPTCHA v2
    • ReCAPTCHA v3
    • hCaptcha
    • Cloudflare Turnstile

All you need to do is include the Basin JS script, add the data-basin-form attribute to your form element, and choose your spam protection option. Basin will take care of the rest.

Note: The main difference between ReCAPTCHA v2 and v3 is that v3 will never prompt or interrupt the user. For more information, visit the ReCAPTCHA versions documentation.

Adapt your form

1. Include the Basin JS script:

Paste the example code below anywhere before the</body> tag:

<script src="https://js.usebasin.com/v2.5.0.min.js" defer></script>

Note

This script is the only script you need to include in your page to use Basin JS. It will automatically include the necessary scripts for the spam protection option you choose.

2. Add data attributes to your form as follows:

  1. Add <data-basin-form> to your form element as well as data-basin-success-action="render" to render a div on success.
  2. Add a div with a class of "w-form-done" somewhere on your page.<div class="w-form-done">Success content here</div>
  3. Add a div with a class of "w-form-fail" somewhere on your page.<div class="w-form-fail">Failure content here</div>
  4. Choose a spam protection option with "data-basin-spam-protection" in your form element. Eg. data-basin-spam-protection='recaptcha'
  5. Enable spam protection in your form spam settings by going to your form -> Settings -> Spam. Eg for ReCAPTCHA:

GIF showing how to enable Google Recaptcha on your form

Your form should look similar to this:

<div class="container">
  <form action="https://usebasin.com/f/YOUR-FORM-ID" method="POST" enctype="multipart/form-data" data-basin-form data-basin-success-action='render' data-basin-spam-protection='recaptcha'>
    <label for="email">Email</label>
    <input type="text" id="email" name="email" placeholder="email.." required>
    <label for="fname">First Name</label>
    <input type="text" id="fname" name="firstname" placeholder="Your name..">
    <label for="theFile">file data:</label>
    <input id="theFile" name="myFile" type="file">
    <input type="submit" value="Submit">
  </form>
  <div class="w-form-done" style="display: none;">Thank you for your submission! 🚀🚀🚀</div>
  <div class="w-form-fail" style="display: none;">Oops, something went wrong 🚨🚨🚨</div>
</div>
Advanced Basin JS example:

Here is an advanced form example using Basin JS where you can specify the success and fail div IDs:

<div class="container">
  <form action="https://usebasin.com/f/YOUR-FORM-ID" method="POST" enctype="multipart/form-data" data-basin-form data-basin-success-id="form1-success" data-basin-error-id="form1-error" data-basin-success-action='render' data-basin-spam-protection='recaptcha'>
    <label for="email">Email</label>
    <input type="text" id="email" name="email" placeholder="email.." required>
    <label for="fname">First Name</label>
    <input type="text" id="fname" name="firstname" placeholder="Your name..">
    <label for="theFile">file data:</label>
    <input id="theFile" name="myFile" type="file">
    <input type="submit" value="Submit">
  </form>
  <div id="form1-success" style="display: none;">Thank you for your submission! 🚀🚀🚀</div>
  <div id="form1-error" style="display: none;">Oops, something went wrong 🚨🚨🚨</div>
</div>

Configuration options

The Basin JS helper script can be provided the following options as attributes on the form:

Form Attribute Values Default Description
data-basin-success-action 'render', 'redirect' 'render' The action to take after a successful form submission, can be 'render' to render a success div or 'redirect ' to follow the redirect url specified in the form settings. (form -> Settings -> General -> Custom Redirect). By default, 'render' is chosen and a div will be rendered.
data-basin-spam-protection 'recaptcha', 'recaptcha-v3', 'hcaptcha', 'turnstile', 'none' 'none' The spam protection option Basin will use for the form. By default, 'none' is selected. The chosen spam protection option must be enabled in your form's settings (form -> Settings -> Spam). For more information on setting up your desired spam protection option see our docs on Spam Filtering
data-basin-success-id Any valid HTML ID '.w-form-done' The ID of the element that should be displayed when the form submission is successful. This div should be hidden by default. If no ID is provided, the default success message will be displayed in the first div with a class of ".w-form-done" to support Webflow out of the box.
data-basin-error-id Any valid HTML ID '.w-form-fail' The ID of the element to display on error. This div should be hidden by default. If no ID is provided, the default success message will be displayed in the first div with a class of ".w-form-fail" to support Webflow out of the box.
data-basin-turnstile-sitekey Your turnstile sitekey N/A The sitekey provided by cloudflare during turnstile setup. This should also be configured in your form's settings (Form -> Settings -> Spam). For more information on setting up turnstile, see our docs on Spam Filtering
data-basin-capture-url true false If true, the url from the form's page will be sent with the submission data as the parameter source_url. Basin will break down this url into the following parameters: source_host, source_path, source_query, source_fragment.

Other special notes:

  1. If no basin-success-id or basin-error-id is provided, the script will look for the default Webflow success (a div with a class of ".w-form-done") and error divs (with a class of ".w-form-fail"). This is to support Webflow out of the box but can be overridden to support any other platform.
  2. This script supports multiple forms on the same page. However, you should then specify the "basin-success-id" and "basin-error-id" for each form. Additionally, all forms on the same page must use the same spam protection option.
  3. Basin JS allows you to style the Google reCAPTCHA logo container by adding a class of "basin-recaptcha-v2-container" to the div.
  4. Make sure to enable your spam protection option in your form spam settings (see above).

Tip

Looking for more ways to protect your form from spam? Checkout our additional spam filtering settings

Progressive Form Capture

Improve data gathering by providing valuable information even from partially filled forms with Progressive Form Capture via Basin JS. Enhance data collection by breaking down a single form into multiple parts. Basin tracks and stores user input as they progress through each section, ensuring a unified submission. If users leave the form before completion, Basin saves their data as a 'draft' for 15 minutes, after which it's labeled as 'abandoned.' Forms that are fully filled out are recorded as 'completed' submissions. Read more about setting up Progressive Form Capture

Submission Handling

BasinJS emits javascript events during and after submission so you can add additional customization to your form's pipeline such as adding Google Tag Manager to your form.

Event Description Detail
basinjsFormSubmitted Emitted when a user submits the form and while the form is being submitted event.detail.form: the HTML form generating the submission
basinjsFormSuccess Emitted when the form has been received successfully by Basin event.detail.form: the HTML form that generated the submission
basinjsFormError Emitted when the form has not been successfully received by Basin due to an error event.detail.form: the HTML form generating the submission, event.detail.error: Error message

Example event listeners

Here are some example event listeners you can add to your page to properly listen for BasinJS events

<script>
  document.addEventListener('basinjsFormSubmitted', function(event) {
    console.log('Form submitted:', event.detail.form);
  });

  document.addEventListener('basinjsFormSuccess', function(event) {
    console.log('Form submission succeeded:', event.detail.form);
  });

  document.addEventListener('basinjsFormError', function(event) {
    console.error('Form submission error:', event.detail.error);
  });
</script>

Versionless Basin JS

If you're using Basin JS and always want the latest version, you can use the following code:

Warning

This will always point to the latest version of Basin JS, and will automatically update when a new version is released. If breaking changes are introduced, this version will include those changes. Use with caution.

<script src="https://js.usebasin.com/latest.min.js" defer></script>

Fixing BasinJS Submission Handling After Exporting Webflow Sites with Udesly

If you're exporting a Webflow site to Netlify using Udesly with Eleventy (11ty) and you need to remove the default form handling from the Udesly-generated script, you can follow these steps:

Steps to Remove Form Handling

  1. Locate the udesly-11ty.min.js File:

    • This file is typically located in your project's assets or scripts directory. It is the minified JavaScript file that Udesly uses for handling various functionalities, including forms.

  2. Prettify the Minified JavaScript:

    • Open the udesly-11ty.min.js file in your code editor (such as Visual Studio Code).
    • Use a built-in or extension-based prettifier to format the minified JavaScript into a more readable form. You can use Shift + Alt + F (Windows/Linux) or Shift + Option + F (Mac) in VS Code to prettify the file.

  3. Remove Form Handling Aspects Using ChatGPT:

    • Copy the prettified JavaScript code.
    • Use ChatGPT or a similar AI tool to analyze the script. Paste the copied code into ChatGPT and ask it to "remove all form handling aspects of this script, and make sure it continues to work."
    • ChatGPT will provide a modified version of the script without the form handling functionality.

  4. Replace the Original Script:

    • Copy the output provided by ChatGPT.
    • Replace the contents of the udesly-11ty.min.js file with the modified code.

  5. Test Your Site:

    • Deploy your changes to Netlify and test your site to ensure that it works as expected without the form handling aspects.
    • Verify that forms no longer have the default handling behavior and that the rest of the site functionality remains intact.

Notes

  • This method is particularly useful if you want to integrate your forms with a custom form handler, such as Basin (usebasin.com), instead of using the default form handling provided by Udesly.
  • Always back up the original udesly-11ty.min.js file before making modifications, so you can revert if necessary.

By following these steps, you can effectively remove the default form handling from the Udesly script while ensuring that your Webflow site functions correctly when deployed to Netlify using Eleventy (11ty).

Changelog

Version 2.5.0

Added

  • Added new option data-basin-capture-url which takes the url from the form's page and sends it with the submission data.

Version 2.4.0

Added

  • Added ability for BasinJS to work if data-basin-form is added outside of a <form> tag, for example in a <div> outside of a form.

Version 2.3.0

Added

  • Added custom events for form submit, submission success, and submission error

Version 2.2.0

Added

Version 2.1.0

Added

  • Added support for Webflow Collections
  • Added helpful console.log if data-basin-form is added outside of a <form> tag.

Version 2.0.3

Fixed

  • Gracefully handle scenarios where forms are not present on a page.

Version 2.0.2

Added

  • Recaptcha v3 support has been added.

Version 2.0.1

Fixed

  • Redirects now utilize Basin's JSON api. Previously, the system was trying to catch the redirect header response from the server, which is not feasible with CORS.

Version 2.0.0

Added

  • Support for recaptcha v2, hCaptcha, and Cloudflare Turnstile has been added.
  • Support for multiple forms on the same page has been added.
  • Support for custom success and error div IDs has been added.
  • Support for redirecting after form submission has been added.

Version 1.0.0

Added

  • This version supports invisible ReCAPTCHA v2, ajax form submission, and success/error divs.