🛠 Bit-Form

Agnostic and performant form state management.

Bit-Form is a powerful, framework-agnostic library designed to handle complex validations, dynamic masks, and conditional logic seamlessly across modern frontend ecosystems. Build your logic once, use it anywhere.

✨ Key Features

• Framework Agnostic Core: Dedicated bindings for React, Vue, and Angular.
• First-Class Validation: Built-in schema resolvers for Zod, Yup, and Joi. Includes native asynchronous validation with configurable trigger (blur by default, change opt-in).
• Advanced Masking System: Extensive list of presets including Currency (BRL, USD, EUR), Documents (CPF, CNPJ, SSN), Dates, and Credit Cards.
• Smart Dependencies: Built-in dependency manager to conditionally hide or require fields using showIf, requiredIf, and dependsOn.
• Computed Fields: Automatically calculate and update form values in real-time based on other field changes.
• Field Arrays: First-class support for dynamic lists with native methods to append, prepend, move, and swap items.
• Draft Persistence: Optional draft persistence with autosave, manual restore, manual clear, and custom storage adapters (Web localStorage, React Native AsyncStorage, or your own adapter).
• Lifecycle Plugins: Plugin system for lifecycle observability (beforeValidate, afterValidate, beforeSubmit, afterSubmit, onFieldChange, onError).
• Time-Travel DevTools: Full history support with Undo/Redo capabilities and a Remote Inspector CLI via WebSocket.

🏎 Performance & Comparison

Bit-Form was built to solve the "heavy form" problem. While most libraries re-render the entire form or require complex memoization to handle dynamic masks and deep validations, Bit-Form uses a subscription-based model that updates only the specific field being touched.

Comparison Table

React Ecosystem

| Feature | Bit-Form | React Hook Form | Formik | TanStack Form | | :-------------------------- | :----------: | :-------------: | :-------: | :-----------: | | Framework Agnostic | ✅ Yes | ❌ No | ❌ No | ✅ Yes | | Built-in Masking | ✅ Advanced | ❌ No | ❌ No | ❌ No | | Re-renders | ⚡ Minimal | ⚡ Minimal | 🐢 High | ⚡ Minimal | | Conditional Logic | ✅ Native | ⚠️ Manual | ⚠️ Manual | ✅ Native | | Time-Travel (Undo/Redo) | ✅ Native | ❌ No | ❌ No | ❌ No | | Remote DevTools | ✅ Yes | ❌ No | ❌ No | ❌ No | | Computed Fields | ✅ Native | ❌ No | ❌ No | ⚠️ Manual |

Vue Ecosystem

| Feature | Bit-Form | VeeValidate | FormKit | | :-------------------------- | :----------: | :---------: | :--------: | | Framework Agnostic | ✅ Yes | ❌ No | ❌ No | | Built-in Masking | ✅ Advanced | ❌ No | ⚠️ Plugins | | Re-renders | ⚡ Minimal | ⚡ Minimal | ⚡ Minimal | | Conditional Logic | ✅ Native | ⚠️ Manual | ✅ Native | | Time-Travel (Undo/Redo) | ✅ Native | ❌ No | ❌ No | | Remote DevTools | ✅ Yes | ❌ No | ❌ No | | Computed Fields | ✅ Native | ❌ No | ⚠️ Manual |

Angular Ecosystem

| Feature | Bit-Form | Angular Reactive Forms | ngx-formly | | :-------------------------- | :----------: | :--------------------: | :--------: | | Framework Agnostic | ✅ Yes | ❌ No | ❌ No | | Built-in Masking | ✅ Advanced | ❌ No | ❌ No | | Re-renders | ⚡ Minimal | ⚡ Minimal | ⚡ Minimal | | Conditional Logic | ✅ Native | ⚠️ Manual | ✅ Native | | Time-Travel (Undo/Redo) | ✅ Native | ❌ No | ❌ No | | Remote DevTools | ✅ Yes | ❌ No | ❌ No | | Computed Fields | ✅ Native | ⚠️ Manual | ⚠️ Manual |

Benchmark Results

Below are measured results from the quality benchmarks currently in this repository. These numbers are not estimated or extrapolated.

• Source tests:
  • quality/bench/rhf-compare.test.ts
  • quality/bench/perf.test.ts
• Reproduce with:
  • npm run test:bench:compare
  • npm run test:bench

React benchmark methodology

The comparison now uses a more realistic and stricter setup:

• same validation semantics across Bit-Form, React Hook Form, Formik, and TanStack Form
• validation is triggered once at the end of each measured cycle
• React commit stabilization before and after each sample
• larger load (600 fields for bulk, 240 iterations for async burst)

React benchmark (Bit-Form vs RHF/Formik/TanStack)

Latest local Node snapshot measured on 20/03/2026:

| Scenario (lower is better) | Bit-Form | RHF | Formik | TanStack | | :------------------------- | :--------- | :------- | :------- | :-------- | | Bulk update (600 fields) | 5.83ms | 556.11ms | 190.63ms | 1552.84ms | | Async burst (240 updates) | 4.57ms | 65.12ms | 22.12ms | 13.50ms |

Bit-Form ratio (bit-form / competitor) from the same snapshot:

• Bulk (median):
  • vs RHF: 0.01
  • vs Formik: 0.03
  • vs TanStack: 0.00
• Async burst (median):
  • vs RHF: 0.07
  • vs Formik: 0.21
  • vs TanStack: 0.34

In practice, this means:

• Bit-Form remains substantially faster than RHF and Formik in bulk-update workloads.
• After the async-validation pipeline refactor, Bit-Form also moved ahead of TanStack in the async burst scenario on this measured environment.
• The benchmark is intentionally conservative, because it waits for React commit stabilization instead of stopping too early.

Internal performance baseline (Bit-Form)

Latest baseline from quality/bench/perf.test.ts:

• 300 field updates: ~20ms
• 1000 field updates in transaction + history: ~45ms
• 400 scoped subscribers: ~9ms
• Async validation burst: ~13ms
• Computed chain fanout (50): ~60ms
• Subscription notify fanout (200): ~15ms

Note: benchmark values vary by machine, Node version, and CI load. Thresholds are calibrated from measured data with CI headroom and are validated in quality/bench.

Why Bit-Form?

1. Store-Level Masking: Bit-Form applies masks in the store layer, which helps keep UI updates localized and predictable in complex forms.
2. Logic Portability: You can share the same BitStore logic (validation, masks, conditional rules, history) across React, Vue, Angular, and React Native bindings.
3. Predictable State: With history, scoped subscriptions, and explicit lifecycle hooks, Bit-Form is a strong fit for multi-step and high-complexity forms where debuggability matters as much as raw speed.

📦 Installation

npm install @lehnihon/bit-form

📚 Documentation

The complete documentation is available in the /docs folder. Explore the guides below to get started:

• Documentation Hub: Start here to navigate by goal (onboarding, troubleshooting, API).

🚀 Getting Started

• Introduction & Installation: Overview and basic setup.
• Core Concepts: Understanding the BitStore and state lifecycle.

🖼 Framework Guides

• React: Using hooks and Context Provider.
• Next.js: Using Bit-Form in App Router/Pages Router with client boundaries ("use client").
• React + native HTML: Generate form wrappers with bit-form add html (Input, Textarea, Select, Checkbox, RadioGroup).
• React + shadcn/ui: Generate form wrappers with bit-form add shadcn (Input, Textarea, Select, Checkbox, Switch, RadioGroup).
• React Native: Mobile specifics and onChangeText mapping.
• Vue: Using composables and InjectionKeys.
• Angular: Reactive forms via Signals.

🛠 Features

• Normalization: Clean runtime state with normalize and control reruns with normalizeDependsOn.
• Validation & Resolvers: Integrating Zod, Yup, and Joi.
• Masks & Formatting: Using and creating input masks.
• Conditional Logic: Managing field dependencies.
• Computed Fields: Handling derived form values.
• Field Arrays: Managing dynamic lists of fields.
• Draft Persistence: Save, restore, and clear local drafts with useBitPersist/injectBitPersist and store-level persist config.
• Lifecycle Plugins: Add plugins to observe validation/submit/field-change events with fail-open behavior.
• File Uploads: Backend-first upload integration with useBitUpload and injectBitUpload.
• Scopes: Per-step validation and status for wizard forms (useBitScope, injectBitScope).
• History & Time Travel: Using Undo/Redo features.

📖 Guides & Examples

• When to Use What: Quick reference for resolver vs asyncValidate vs setServerErrors, normalize vs computed vs transform, and conditional fields.
• Troubleshooting: Debug common form setup, validation, and devtools issues.
• Testing Guide: Unit, integration, and e2e testing strategies.
• Performance Guide: Optimize large forms and subscription patterns.
• Accessibility Guide: Build accessible form experiences across frameworks.
• Compatibility Matrix: Runtime and framework target baseline.
• Release Gates: Pre-release quality and docs synchronization checks.
• FAQ: Quick answers for common implementation questions.
• Example Template: Editorial template for consistent, copy-paste-ready examples.
• Complete Form Example: End-to-end example with masks, asyncValidate, conditional logic, scopes, history, and DevTools.
• Conditional + Server Validation Example: Dynamic fields with 422/server mapping workflow.
• Multi-Step + Draft Example: Scope-based wizard with persistence controls.
• Array Reorder Example: Stable keys and automatic error reallocation during reorder/remove.
• Plugin + DevTools Example: Lifecycle audit logs with local timeline inspection.
• Upload Integration Example: Backend-first upload example using useBitUpload/injectBitUpload.
• E-commerce Checkout Example: Advanced nested + arrays + computed + async shipping quote flow.
• Server Errors: Client validation (resolver/asyncValidate) vs API 422 handling (setServerErrors, onSubmit).

🔍 DevTools & CLI

• DevTools Overview: Configuration (devTools: true or { mode: "remote" }).
• Floating Panel: In-app inspector (local mode).
• CLI & Remote Dashboard: bit-form devtools + WebSocket for React Native / remote debugging.
• CLI add: Generate Bit-Form wrappers with bit-form add shadcn [input|textarea|select|checkbox|switch|radio-group] or bit-form add html [input|textarea|select|checkbox|radio-group] — see React + shadcn and React + native HTML.

📑 Reference

• API Reference: Full BitStore class documentation.
• Type Definitions: Core TypeScript interfaces and types.
• Advanced Core API: Public advanced exports for custom adapters and tooling.

🤝 Contributing

Contributions are welcome! Feel free to open issues or submit pull requests.

📄 License

MIT