formisch

Formisch is designed to be framework-agnostic at its core while remaining native to the specific UI framework you are using. Supported frameworks include:

• Angular
• Preact
• Qwik
• React
• React Native
• SolidJS
• Svelte
• Vue

In the context of Formisch for React Native, a FieldElement is a structural subset of imperative methods provided by React Native host component instances (like TextInput).

Because React Native lacks a DOM, FieldElement acts as an abstraction that allows Formisch to interact with focusable native components via refs without requiring a direct dependency on the react-native package. This allows the field store to manage focus for any component that implements the required interface.

A FormSchema is a type definition representing the Valibot schemas allowed to serve as the root of a Formisch form.

Because forms require an object-based structure for field mapping, a FormSchema is structurally constrained to any schema that produces an object output. This includes:

• Object schemas
• Combinators over objects (e.g., intersect, union, variant)
• lazy schemas wrapping the above
• Generic object schemas (e.g., v.GenericSchema<{ ... }>)

Note: For schemas used for individual nested fields within a form, use the Schema type instead.

Formisch is a schema-first, headless, and fully type-safe library for managing form state. It uses a single Valibot schema to drive both runtime validation and TypeScript types, eliminating the need for separate type definitions or resolvers.

Key characteristics:

• Headless: You maintain full control over markup and styling.
• Type-safe: The path prop in fields is fully typed against your schema.
• Performant: Uses fine-grained signals so only changed fields re-render.
• Framework-agnostic core: Supports Angular, Preact, Qwik, React, React Native, SolidJS, Svelte, and Vue without an abstraction tax, as it swaps in the framework's native reactivity at build time.

Your schema should exactly reflect the data structure expected upon submission. If a field is not required, use Valibot's v.optional(...) function. Formisch validates the form values against this schema before submission, preventing submission if the data does not match the definition.

import * as v from 'valibot';

const ProfileSchema = v.object({
  name: v.pipe(v.string(), v.nonEmpty()),
  bio: v.optional(v.string()), // <- Optional field
});

By default, Formisch fields are uncontrolled, relying on native browser behavior. However, you must use controlled fields when you need to:

• Set initial values programmatically.
• Manipulate field values via methods like setInput.
• Use specific HTML attributes like value, checked, or selected to sync the UI with the form state.

To control a field, you must explicitly bind the field's value to the input's attribute and ensure that updates are sent back to Formisch using the field's input handler.

<Field of={loginForm} path={['firstName']}>
  {(field) => (
    <input
      {...field.props}
      type="text"
      // Pass value or empty string to ensure the input is controlled
      value={field.input ?? ''}
    />
  )}
</Field>

The order of fields in your Valibot schema determines the focus behavior during validation errors. When a form is submitted with invalid values, Formisch automatically focuses the first field that failed validation.

Best Practice: Define your fields in the schema in the same order they appear visually in your UI. This ensures that when a user submits an invalid form, the focus moves to the first invalid field at the top of the form rather than jumping to a field further down the page.

All reactive state in Formisch is managed via a Signal<T> interface. This allows for fine-grained updates: when a specific field's value changes, only the components observing that specific signal re-render, rather than the entire form.

Every field in the store carries its own signals for:

• errors
• isTouched
• isEdited
• isDirty
• input (for value fields)

Structural components like objects and arrays use a children collection to manage their nested fields. Because the store hierarchy is pre-allocated based on your Valibot schema, methods can update individual signals directly without expensive object diffing or path lookups.

interface Signal<T> {
  get value(): T;
  set value(nextValue: T): void;
}