hubspot-multistep-form/README.md

hubspot-multistep-form is a lightweight, zero-backend, multi-step form builder designed to sync user input directly to HubSpot forms. Ideal for lead capture, surveys, onboarding flows, and more.

# hubspot-multistep-form

A lightweight, vanilla JavaScript utility for building multi-step static forms that **sync seamlessly with HubSpot** forms — no backend needed.

Perfect for lead generation, surveys, onboarding flows, and more.

---


## 🚀 Installation

```bash
npm install hubspot-multistep-form
````

---


## ✨ Features

* 🎯 Multi-step static form logic
* 🔄 Syncs all inputs (`input`, `textarea`, `select`, `checkbox`, `radio`) to HubSpot
* ✅ Customizable required field validation
* 📊 Animated progress bar support
* ⏳ Buffer loading logic for delayed HubSpot embed forms
* 🔁 Retry attempts if HubSpot form takes time to load
* 🔍 Customizable thank-you message + loader display
* 📦 Zero dependencies

---


## 🧠 Usage Example

### HTML

```html
<div class="progressBarContainer">
  <div class="progressBar" style="width: 0%; height: 4px;"></div>
</div>

<div class="formWrapper">
  <div class="step active">
    <div class="field">
      <input name="firstname" required />
    </div>
    <div class="field">
      <input name="email" required />
    </div>
  </div>
  <div class="step">
    <div class="field">
      <textarea name="message"></textarea>
    </div>
  </div>
  <input type="submit" value="Submit" />
</div>

<div class="HubspotForm">
  <!-- HubSpot embed form -->
</div>

<div class="thankyouMessage" style="display: none;">
  Thanks for submitting!
</div>

<div class="formLoader" style="display: none;">
  Submitting...
</div>

<div class="nextPrevious">
  <button class="prev">Previous</button>
  <button class="next">Next</button>
</div>
```

---


### JavaScript

#### 🔁 With NPM:

```js
import { initHubspotMultistepForm } from 'hubspot-multistep-form';

initHubspotMultistepForm({
  wrapperSelector: '.formWrapper',
  hubspotFormSelector: '.HubspotForm form',
  thankYouSelector: '.thankyouMessage',
  nextPreviousSelector: '.nextPrevious',
  submitMessageSelector: '.submitted-message',
  progressBarSelector: '.progressBar',
  loaderSelector: '.formLoader',
  hubspotLoadBuffer: 2000,
  submitResponseTimeout: 6000,
  validationRules: {
    email: (val) => /\S+@\S+\.\S+/.test(val)
  },
  skipValidation: ['website'],
  onSuccessSubmit: () => console.log('Submitted successfully!'),
  onFailedSubmit: () => alert('Form submission failed.'),
  onError: () => alert('HubSpot form failed to load.')
});
```

#### 🌐 Or with CDN:

```html
<script src="https://cdn.jsdelivr.net/npm/hubspot-multistep-form@{version}/dist/index.iife.js"></script>
<script>
  initHubspotMultistepForm({
    // same config as above
  });
</script>
```

Replace `{version}` with the latest published version.

---


## 🔧 API: Configuration Options

| Option                  | Type       | Default              | Description                                                |
| ----------------------- | ---------- | -------------------- | ---------------------------------------------------------- |
| `wrapperSelector`       | `string`   | `.formWrapper`       | Static form container selector                             |
| `hubspotFormSelector`   | `string`   | `.HubspotForm form`  | Embedded HubSpot form selector                             |
| `thankYouSelector`      | `string`   | `.thankyouMessage`   | Selector for post-submit success message                   |
| `progressBarSelector`   | `string`   | `.progressBar`       | Progress bar element selector                              |
| `loaderSelector`        | `string`   | `.formLoader`        | Loader element shown during submission                     |
| `nextPreviousSelector`  | `string`   | `.nextPrevious`      | Container for next/previous buttons                        |
| `submitMessageSelector` | `string`   | `.submitted-message` | HubSpot's post-submit confirmation element                 |
| `skipValidation`        | `string[]` | `[]`                 | Field `name`s to skip validation                           |
| `validationRules`       | `object`   | `{}`                 | Add custom validation rules (optional/future-ready)        |
| `hubspotLoadBuffer`     | `number`   | `1500`               | Delay (ms) before checking if HubSpot form is loaded       |
| `submitResponseTimeout` | `number`   | `5000`               | Timeout (ms) to stop polling for HubSpot’s success message |
| `onSuccessSubmit`       | `function` | `() => {}`           | Callback when form is successfully submitted               |
| `onFailedSubmit`        | `function` | `() => {}`           | Callback if form was submitted but HubSpot didn’t respond  |
| `onError`               | `function` | `() => {}`           | Callback if HubSpot form fails to load in time             |

---


## 📄 License

MIT © [Hub Resolution Private Limited.](mailto:tejas@hubresolution.com)

See the [LICENSE](./LICENSE) file for details.