Graph-based form engine that eliminates "condition hell" in complex multi-step workflows. Stop writing nested if-else. Start building state machines.
Core Features
Every form library handles the simple case. React Form Atlas handles the impossible one.
Navigation that adapts. Define your form as a finite state machine — not a series of nested if-else statements. The engine calculates valid transitions at runtime based on current context.
State MachineBuilt-in persistence. Automatically saves form state to IndexedDB or LocalStorage so users never lose their progress — even on page refresh.
Auto-PersistPrevent impossible states. The engine checks the entire future graph to ensure current data doesn't block completion before the user even gets there.
Future-AwareReal percentages — not fake ones. Calculate progress based on the actual complexity of the specific path the user is currently traversing. No more "99% done" that takes 10 minutes.
Path-Aware ProgressArchitecture
React Form Atlas is a graph-based form engine that treats your form as a Directed Acyclic Graph (DAG) instead of a linear array of steps. This fundamental shift eliminates "condition hell" and makes complex branching logic declarative and maintainable.
Linear arrays ([Step1, Step2, Step3]) require complex imperative logic to handle
branching. Resulting in brittle if/else soup.
Declarative graph schemas define nodes and edges. The engine handles navigation, history, and progress calculation automatically.
"Eliminate 'Condition Hell' — Build forms that scale from 5 to 500 steps without breaking a sweat."
Each step in your form is a state. States contain transitions, metadata (weight, validation), and custom properties like ARIA labels.
Edges between states. They define the "map" of your form. Can be simple strings or complex conditional objects that evaluate context.
The global state store. Accumulates data as users progress, shared across all form steps.
Automatic persistence via IndexedDB so users can resume exactly where they left off.
Numerical weights assigned to states to make progress bar calculation accurate for every path.
Instead of validating only the current step, React Form Atlas validates the entire future path. If a user enters data that makes a future required step impossible to complete (e.g., age restriction), they are alerted immediately—preventing wasted time on intermediate steps.
Quick Start
Install the package
Define your schema
Hook into your component
Let's build a complete onboarding flow with conditional branching using the React bridge.
Create a schema.ts file to define your form's topology. Notice the weight
field—this is used for accurate progress calculation.
export const onboardingSchema = { id: 'onboarding', initial: 'welcome', states: { welcome: { on: { NEXT: 'userType' } }, userType: { on: { BUSINESS: 'bizDetails', INDIVIDUAL: 'personalDetails' } }, bizDetails: { on: { NEXT: 'complete' }, meta: { weight: 3 } }, personalDetails: { on: { NEXT: 'complete' }, meta: { weight: 1 } }, complete: { type: 'final' } } };
Apply the useReactForm hook. It returns a stable object containing the current state and
transition functions.
import { useReactForm } from 'react-form-atlas'; function MyForm() { const { currentState, transition, progress, isReady } = useReactForm({ schema: onboardingSchema, autoSave: true }); if (!isReady) return <div>Loading...</div>; return ( <div> <ProgressBar width={progress} /> {currentState === 'welcome' && ( <button onClick={() => transition('NEXT')}>Join</button> )} </div> ); }
Complex schemas can be hard to track. Use the visualizer CLI to generate an interactive map of your form.
npx react-form-atlas-visualizer schema.json -o map.html
API Reference
The useReactForm hook returns a stable
object — all methods are memoized.
| Method / Property | Params | Description | Returns |
|---|---|---|---|
| transition() | event: string data?: object |
Move to the next state based on the schema graph. Fires guards and updates context atomically. | Promise<void> |
| back() | — | Navigate to the previous state in the history stack. Respects no-back flags per state. | Promise<void> |
| updateContext() | data: Partial<T> | Deep-merge new data into the global form context without triggering a transition. | void |
| progress | — | Weighted completion percentage (0–100) of the current user-specific path. | number |
| currentState | — | The string key of the currently active schema state. | string |
| context | — | Live reference to the accumulated form context object. | T |
| reset() | — | Clear all context and history, returning to the initial state. Also purges any draft-lock storage. | void |
Every function in the engine is built for reliability. All state changes are atomic and irreversible (unless you move back).
Evaluates guards for the given event, merges data into the global context, and updates
the state. If no valid transition is found, it throws a TransitionError.
Navigates to the previous state in the history stack. Respects the allowBack flag in
your schema. Automatically syncs with storage.
Deep-merges new data into the form context without triggering state transitions. Useful for per-field validation or temporary UI state.
Wipes all context, history, and storage snapshots. Returns the engine to its initial state—clean slate.
React Form Atlas is built with 100% type safety. All schemas and hooks are strictly typed for a superior developer experience.
interface FormSchema { id: string; initial: string; states: Record<string, FormState>; } interface FormState { id: string; on?: Record<string, string | ConditionalTransition>; meta?: { weight?: number; validation?: ValidationRule[]; }; }
Generate documentation automatically from your code. Use the CLI tool to generate Mermaid diagrams or interactive HTML reports.
react-form-atlas-visualizer <schema.json> --output report.html