aw-wizard-forms

A lightweight, Typeform-style multi-step form wizard built with Lit Web Components.

Features

• Lightweight: ~15KB (Brotli) / ~18KB (gzip) including Lit
• Single Script Tag: Easy embedding with WizardForm.init()
• Declarative Components: HTML-based composition with custom elements
• Keyboard Navigation: A-Z badges, Enter/Escape, arrow keys
• Validation: Debounced validation with custom validators
• Theming: CSS Custom Properties (--wf-* prefix)
• Adapters: HubSpot, Webhook, RevenueHero integrations

Installation

CDN (Recommended)

<!-- Pin to specific version (recommended) -->
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/wizard-form.min.js"></script>

<!-- Or use latest (auto-updates) -->
<script src="https://cdn.jsdelivr.net/npm/aw-wizard-forms@latest/dist/wizard-form.min.js"></script>

Replace 4.9.3 with your desired version. See npm for available versions.

Quick Start

<wizard-form id="demo-form">
  <wf-step data-step="1">
    <wf-input name="fullName" label="Full Name" required></wf-input>
    <wf-email name="email" label="Email" work-email required></wf-email>
  </wf-step>

  <wf-step data-step="2">
    <wf-options name="companySize" required>
      <wf-option value="1-10">1-10 employees</wf-option>
      <wf-option value="11-50">11-50 employees</wf-option>
      <wf-option value="51+">51+ employees</wf-option>
    </wf-options>
  </wf-step>

  <div slot="success">
    <h2>Thank you!</h2>
    <p>We'll be in touch soon.</p>
  </div>
</wizard-form>

<script>
  WizardForm.init({
    container: '#demo-form',
    adapter: 'hubspot',
    hubspot: {
      portalId: '12345',
      formId: 'abc-123',
    },
    onSubmit: (data) => console.log('Submitted:', data),
    onSuccess: () => console.log('Success!'),
    onError: (err) => console.error('Error:', err),
  });
</script>

Components

| Component | Description | |-----------|-------------| | <wizard-form> | Main container/orchestrator | | <wf-step> | Step container (use data-step="N") | | <wf-input> | Text input with validation | | <wf-number> | Number input with min/max/step | | <wf-email> | Email input with work-email validation | | <wf-textarea> | Multiline text input | | <wf-options> | Radio/checkbox option group | | <wf-option> | Individual option card |

Adapters

HubSpot

WizardForm.init({
  container: '#form',
  adapter: 'hubspot',
  hubspot: {
    portalId: '12345',
    formId: 'abc-123',
    fieldMapping: {
      fullName: 'firstname', // Map form fields to HubSpot fields
    },
  },
});

Webhook

WizardForm.init({
  container: '#form',
  adapter: 'webhook',
  webhook: {
    url: 'https://api.example.com/submit',
    method: 'POST',
    headers: {
      'X-API-Key': 'your-key',
    },
  },
});

RevenueHero

WizardForm.init({
  container: '#form',
  adapter: 'revenuehero',
  revenuehero: {
    routerId: 'your-router-id',
  },
});

Theming

Customize with CSS Custom Properties:

wizard-form {
  --wf-color-primary: #8b5cf6;
  --wf-color-surface: #f8f9fa;
  --wf-color-text: #212529;
  --wf-color-error: #dc3545;
  --wf-radius-lg: 12px;
  --wf-font-size-base: 16px;
}

Keyboard Shortcuts

| Key | Action | |-----|--------| | A-Z | Select option by badge | | Enter | Next step / Submit | | Escape | Previous step | | ↑/↓ | Navigate options | | Tab | Navigate fields |

Development

# Install dependencies
yarn

# Development server
yarn dev

# Run tests
yarn test          # Unit tests (Vitest)
yarn test:e2e      # E2E tests (Playwright)

# Build
yarn build

# Check bundle size
yarn size

Bundle Size

| Compression | Size | |-------------|------| | Raw | 78KB | | Gzip | 17.7KB | | Brotli | 15.5KB |

Browser Support

Modern browsers (ES2020+):

• Chrome 80+
• Firefox 78+
• Safari 14+
• Edge 80+

Known Issues

Step disappears intermittently with submit-on-step enabled

Status: Under investigation

When using the submit-on-step attribute for partial HubSpot submissions, the next step may occasionally disappear (blank content area while progress bar updates correctly). This is a rare, intermittent issue.

Workaround: If you encounter this, refresh the page. The issue does not affect final form submission.

Debug: Run this in console when it occurs to help diagnose:

document.querySelectorAll('wf-step').forEach((step, i) => {
  console.log(`Step ${i + 1}:`, {
    active: step.hasAttribute('active'),
    display: getComputedStyle(step).display,
    height: step.offsetHeight
  });
});

Track progress: GitHub Issue #31

License

MIT © Atomicwork