React Hook Form Integration
Relevant source files
The following files were used as context for generating this wiki page:
The integration of data-path with React Hook Form (RHF) provides a type-safe mechanism for binding deeply nested form fields to a central state. By using Proxy-based lambda expressions, developers can generate the dot-notation string names required by RHF's register function while maintaining full IDE autocomplete and compile-time validation.
This approach replaces fragile string-based paths (e.g., "users.0.firstName") with typed paths that automatically update during refactoring and ensure that form fields strictly match the underlying data structure.
Sources: README.md:12-25, skills/data-path/SKILL.md:43-52
Core Architecture and Data Flow
The integration relies on the path<T> utility to capture object access patterns and convert them into a serialized string representation. In the context of React Hook Form, the library acts as a bridge between the TypeScript schema and the form's internal registration system.
Path-to-String Workflow
The following diagram illustrates how a typed lambda is converted into a string that RHF can consume:
The path function creates a Proxy that records every property access or array index within the lambda, storing them as segments before joining them with dots.
Sources: src/impl/path-impl.ts:46-60, src/types.ts:162-171, README.md:27-38
Implementation Details
The $ Property
The primary integration point with React Hook Form is the $ property. It returns the string representation of the captured path (e.g., "profile.firstName"), which matches the format expected by the RHF register and control APIs.
| Property | Type | Description |
|---|---|---|
path.$ | string | The serialized dot-notation string (e.g., users.0.name). |
path.segments | Array<string | number> | The raw array of keys used to build the string. |
Sources: src/types.ts:140-155, src/impl/path-impl.ts:46-52
Handling Dynamic Indices
A common requirement in RHF is binding fields within a useFieldArray loop. data-path allows capturing the loop index i directly within the lambda. Because the lambda is executed once during the path creation call, it captures the current value of the index from the surrounding scope.
// Example within a .map() loop from useFieldArray
const namePath = path<FormValues>(p => p.users[i].firstName);
// namePath.$ results in "users.0.firstName", "users.1.firstName", etc.
Sources: README.md:183-205, src/tests/path.spec.ts:24-28, skills/data-path/SKILL.md:47-52
Integration Patterns
Component Binding
When creating reusable input components, data-path can be used to pass type-safe field references.
| Integration Step | Action |
|---|---|
| Type Definition | Define the global FormValues interface. |
| Path Creation | Initialize a path using path<FormValues>(p => ...). |
| Registration | Pass path.$ to the register function. |
| Validation | Use unsafePath to map RHF errors back to the path objects. |
Sources: README.md:183-205, skills/data-path/SKILL.md:105-115
Relationship with Validation
When using Zod with React Hook Form, validation errors often return a path array. The unsafePath utility can be used to convert these arrays back into path objects for comparison with form fields.
Comparison with Standard RHF Usage
| Feature | Standard RHF | With data-path |
|---|---|---|
| Field Naming | Manual string literals | Type-safe lambda |
| Autocomplete | None (unless using heavy TS templates) | Full IDE support |
| Refactoring | Manual find/replace | Automatic (compiler-assisted) |
| Nested Arrays | String interpolation: `users.${i}.name` | Natural access: p.users[i].name |
Sources: README.md:5-10, skills/data-path/SKILL.md:5-12
The integration of data-path into React Hook Form workflows eliminates "stringly-typed" field management. By leveraging the path.$ string serialization and the library's ability to capture runtime variables like array indices, developers can build complex, nested forms that are verified by the TypeScript compiler.