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

$3

``html





`

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

Quick Start

`html








1-10 employees
11-50 employees
51+ employees




`

Components

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

Adapters

$3

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

$3

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

$3

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

Theming

Customize with CSS Custom Properties:

`css
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

`bash


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

$3

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:
`javascript
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