# Formisch The lightweight, schema-first, and fully type-safe form library for React, Solid, Vue, Svelte and more. ## Hooks ### useForm Creates a reactive form store from a form configuration. The form store manages form state and provides reactive properties. ```ts const form = useForm(config); ``` #### Generics - `TSchema` #### Parameters - `config` ##### Explanation `useForm` creates a reactive form store that manages form state using the provided Valibot schema. Validation runs when a field is blurred or the form is submitted by default, but this can be customized with the `validate` and `revalidate` options. #### Returns - `form` #### Related The following APIs can be combined with `useForm`. ##### Hooks ##### Components ##### Methods ### useField Creates a reactive field store of a specific field within a form store. ```ts const field = useField(form, config); ``` #### Generics - `TSchema` - `TFieldPath` #### Parameters - `form` - `config` ##### Explanation With `useField` you create a reactive field store for a specific field path within your form. The field store provides reactive access to the field's input value, validation errors, touched state, and more. It also includes a `props` object that you can spread onto an HTML input or textarea element to automatically handle user interactions like focus, blur, and input events. #### Returns - `field` #### Related The following APIs can be combined with `useField`. ##### Hooks ##### Components ##### Methods ### useFieldArray Creates a reactive field array store of a specific field array within a form store. ```ts const fieldArray = useFieldArray(form, config); ``` #### Generics - `TSchema` - `TFieldArrayPath` #### Parameters - `form` - `config` ##### Explanation With `useFieldArray` you create a reactive field array store for a specific array field within your form. The field array store provides reactive access to the array items (by their IDs), validation errors, touched state, and more. This is particularly useful when working with dynamic arrays of fields that users can add or remove. #### Returns - `fieldArray` #### Related The following APIs can be combined with `useFieldArray`. ##### Hooks ##### Components ##### Methods ## Components ### Form Form component that manages form submission and applies internal state. Wraps form element and passes submission events to the provided handler. ```tsx ``` #### Generics - `TSchema` #### Properties - `of` - `children` - `onSubmit` ##### Explanation The `Form` component wraps a native HTML `

` element and provides form submission handling. It automatically prevents the default form submission behavior and calls the `onSubmit` handler when the form is submitted and validation succeeds. The component uses the `of` prop to reference the form store and renders the `children` elements within the form. It also sets `novalidate` on the form element to disable browser validation, as Formisch handles validation internally. #### Related ##### Hooks ##### Components ##### Methods ### Field Headless form field component that provides reactive properties and state. The field component takes a form store, path to field, and a render function that receives a field store to display field state and handle user interactions. ```tsx children ``` #### Generics - `TSchema` - `TFieldPath` #### Properties - `of` - `path` - `children` ##### Explanation The `Field` component is a headless component that doesn't render any UI itself. Instead, it provides a render prop function via the `children` prop that receives a `FieldStore` containing all the reactive state and props needed to render a form field. The component automatically handles field registration, validation, and state management through the `of` prop that references the form store. #### Related ##### Hooks ##### Components ### FieldArray Headless field array component that provides reactive properties and state for managing array fields. The field array component takes a form store, path to array field, and a render function that receives a field array store to manage array items and handle array operations. ```tsx children ``` #### Generics - `TSchema` - `TFieldArrayPath` #### Properties - `of` - `path` - `children` ##### Explanation The `FieldArray` component is a headless component that doesn't render any UI itself. Instead, it provides a render prop function via the `children` prop that receives a `FieldArrayStore` containing all the reactive state and methods needed to manage an array of form fields. The component automatically handles array field registration, validation, and state management through the `of` prop that references the form store. #### Related ##### Hooks ##### Components ##### Methods ## Methods ### focus Focuses the first input element of a field. This is useful for programmatically setting focus to a specific field, such as after validation errors or user interactions. ```ts focus(form, config); ``` #### Generics - `TSchema` - `TFieldPath` #### Parameters - `form` - `config` ##### Explanation The `form` parameter is the form store containing the field to focus. The `config` parameter specifies which field to focus using the `path` property, and can optionally include additional focus options. #### Related ##### Primitives ##### Methods ### getAllErrors Retrieves all error messages from all fields in the form by walking through the entire field store tree. This is useful for displaying a summary of all validation errors across the form. ```ts const errors = getAllErrors(form); ``` #### Parameters - `form` ##### Explanation The `form` parameter is the form store to retrieve errors from. The function walks through the entire field store tree to collect all validation error messages from every field. #### Returns - `result` #### Related ##### Primitives ##### Methods ### getDirtyInput Retrieves only the dirty input values of a specific field or the entire form. Object keys whose subtree contains no dirty descendant are omitted; arrays are treated as atomic and returned in full whenever any descendant is dirty. Returns `undefined` if no field in the inspected subtree is dirty. ```ts const input = getDirtyInput(form); const input = getDirtyInput(form, config); ``` #### Generics - `TSchema` - `TFieldPath` #### Parameters - `form` - `config` ##### Explanation The `form` parameter is the form store to retrieve dirty input from. The optional `config` parameter scopes the result to a specific field path - if omitted, returns dirty input from the entire form. The returned value is a partial of the inspected input shape containing only the fields whose `isDirty` flag is set, which is useful for submitting only the values that changed since the start input. Arrays are treated as atomic — when any descendant of an array is dirty, the full current array is returned. Internally, the function walks the form's field tree and asks `getFieldBool` whether each branch contains a dirty descendant. Because that check is itself recursive, the cost is effectively linear in field count for typical balanced forms (shallow and wide) and degrades toward `O(N²)` for deeply nested trees. Call this method from submit or blur handlers rather than from tight reactive loops on large forms. #### Returns - `result` #### Related ##### Methods ### getDirtyPaths Returns a list of paths to dirty fields in the form. Object branches are recursed into; arrays are treated as atomic — when any descendant of an array is dirty, only the array's own path is returned. ```ts const paths = getDirtyPaths(form); const paths = getDirtyPaths(form, config); ``` #### Generics - `TSchema` - `TFieldPath` #### Parameters - `form` - `config` ##### Explanation The `form` parameter is the form store to inspect. The optional `config` parameter scopes the search to a single subtree via its `path` property. Object branches are recursed into and clean keys are omitted; arrays are atomic, so when any descendant of an array is dirty, the result includes the array's own path rather than the paths of its individual items. Returns an empty array if the inspected subtree contains no dirty fields. When `path` targets a dirty array or value field, the result contains that path. Internally, the function walks the form's field tree and asks `getFieldBool` whether each branch contains a dirty descendant. Because that check is itself recursive, the cost is effectively linear in field count for typical balanced forms (shallow and wide) and degrades toward `O(N²)` for deeply nested trees. Call this method from submit or blur handlers rather than from tight reactive loops on large forms. #### Returns - `result` #### Related ##### Methods ### getErrors Retrieves error messages from the form. When called without a config, returns form-level errors. When called with a path, returns errors for that specific field. ```ts const errors = getErrors(form); const errors = getErrors(form, config); ``` #### Generics - `TSchema` - `TFieldPath` #### Parameters - `form` - `config` ##### Explanation The `form` parameter is the form store to retrieve errors from. The optional `config` parameter specifies which errors to retrieve - either form-level errors (when omitted) or field-specific errors (when a `path` is provided). #### Returns - `result` #### Related ##### Primitives ##### Methods ### getInput Retrieves the current input value of a specific field or the entire form. Returns a partial object as not all fields may have been set. ```ts const input = getInput(form); const input = getInput(form, config); ``` #### Generics - `TSchema` - `TFieldPath` #### Parameters - `form` - `config` ##### Explanation The `form` parameter is the form store to retrieve input from. The optional `config` parameter specifies which field to get input from - if omitted, returns input from the entire form. #### Returns - `result` #### Related ##### Primitives ##### Methods ### handleSubmit Creates a submit event handler for the form that prevents default browser submission, validates the form input, and calls the provided handler if validation succeeds. This is designed to be used with the form's onsubmit event. ```ts const result = handleSubmit(form, handler); ``` #### Generics - `TSchema` #### Parameters - `form` - `handler` ##### Explanation The `form` parameter is the form store to handle submission for. The `handler` parameter can be a `SubmitHandler` (no event) or a `SubmitEventHandler` (with event) that gets called with the validated form output if validation succeeds. #### Returns - `result` #### Related ##### Primitives ##### Methods ### insert Inserts a new item into a field array at the specified index. All items at or after the insertion point are shifted up by one index. ```ts insert(form, config); ``` #### Generics - `TSchema` - `TFieldArrayPath` #### Parameters - `form` - `config` ##### Explanation The `form` parameter is the form store containing the field array. The `config` parameter specifies the path to the field array, the index where to insert the new item, and optional initial input values for the new item. #### Related ##### Primitives ##### Methods ### move Moves an item within a field array from one index to another. All items between the old and new positions are shifted accordingly. ```ts move(form, config); ``` #### Generics - `TSchema` - `TFieldArrayPath` #### Parameters - `form` - `config` ##### Explanation The `form` parameter is the form store containing the field array. The `config` parameter specifies the path to the field array and the indices to move the item from and to. #### Related ##### Primitives ##### Methods ### pickDirty Picks only the dirty parts of the given value, using the form's dirty tree as a structural mask. Object keys whose subtree contains no dirty descendant are omitted; arrays are treated as atomic and returned in full whenever any descendant is dirty. Returns `undefined` if no field is dirty. Where the supplied value's shape diverges from the form's input shape — for example, a field expected to be an object holds a primitive, `null` or array — that branch is returned as-is. Useful for filtering a validated output to just the changed parts before submitting. ```ts const dirty = pickDirty(form, config); ``` #### Generics - `TSchema` - `TValue` #### Parameters - `form` - `config` ##### Explanation The `form` parameter is the form store providing the dirty mask. The `config` parameter must include a `from` value to filter. The value's shape is expected to match the form's input shape — wherever the shapes diverge (e.g. an object key in the form holds a primitive, `null` or array in the supplied value), that branch is returned as-is so the divergence is preserved in the result. Use this when a Valibot schema transformation produces a value of a different shape than the form's input and you want to ship only the dirty parts of that output. Internally, the function walks the form's field tree alongside the supplied value, using `getFieldBool` to skip clean subtrees and a constant-time check at each node to verify shape alignment. Because the dirty check is itself recursive, the cost is effectively linear in field count for typical balanced forms (shallow and wide) and degrades toward `O(N²)` for deeply nested trees. Call this method from submit or blur handlers rather than from tight reactive loops on large forms. #### Returns - `result` #### Related ##### Methods ### remove Removes an item from a field array at the specified index. All items after the removed index are shifted down by one. ```ts remove(form, config); ``` #### Generics - `TSchema` - `TFieldArrayPath` #### Parameters - `form` - `config` ##### Explanation The `form` parameter is the form store containing the field array. The `config` parameter specifies the path to the field array and the index of the item to remove. #### Related ##### Primitives ##### Methods ### replace Replaces an item in a field array at the specified index with a new item. ```ts replace(form, config); ``` #### Generics - `TSchema` - `TFieldArrayPath` #### Parameters - `form` - `config` ##### Explanation The `form` parameter is the form store containing the field array. The `config` parameter specifies the path to the field array, the index of the item to replace, and the new item values. #### Related ##### Primitives ##### Methods ### reset Resets the form or a specific field to its initial state or to a new initial input. Optionally keeps certain states like input values, touched state, or errors. ```ts reset(form); reset(form, config); ``` #### Generics - `TSchema` - `TFieldPath` #### Parameters - `form` - `config` ##### Explanation When called without a config or with `path` set to `undefined`, the entire form is reset. When a `path` is provided, only that specific field and its nested fields are reset. By default, the form resets to its original initial input. However, you can pass a new `initialInput` in the config to update the form's baseline data. This is useful when remote data has changed and the form needs to reflect the updated values. Combined with `keepInput`, `keepTouched`, `keepErrors`, and `keepSubmitted`, you can update the initial state without overwriting the user's current edits. ###### More context on dirty tracking Formisch distinguishes between two concepts: - **Initial input**: the baseline value used for dirty tracking (often the server state). - **Current input**: the value the user is currently editing (the client state). Calling `reset` updates the initial input (baseline). Depending on the `keep*` options, it can also overwrite the current input, or keep it and just recompute state like `isDirty` based on the new baseline. > If the initial input is `null` or `undefined`, Formisch does not treat an empty string or `NaN` as dirty. This helps when HTML inputs produce `''` or `NaN` for "empty" values. #### Related ##### Primitives ##### Methods ### setErrors Sets or clears error messages on the form or a specific field. This is useful for setting custom validation errors that don't come from schema validation. ```ts setErrors(form, config); ``` #### Generics - `TSchema` - `TFieldPath` #### Parameters - `form` - `config` ##### Explanation The `form` parameter is the form store to set errors on. The `config` parameter specifies the path and error messages to set, or can be set to null to clear existing errors. #### Related ##### Primitives ##### Methods ### setInput Sets input values for the form or a specific field programmatically. ```ts setInput(form, config); setInput(form, config); ``` #### Generics - `TSchema` - `TFieldPath` #### Parameters - `form` - `config` ##### Explanation The `form` parameter is the form store to set input on. The `config` parameter specifies the path to the field and the new input values to set. > `setInput` updates the **current input** (what the user is editing), but it does not change the **initial input** (the baseline used for `isDirty`). If your baseline data changes (e.g. after refetching from the server), prefer `reset` with a new `initialInput`. #### Related ##### Primitives ##### Methods ### submit Programmatically requests form submission by calling the native `requestSubmit()` method on the underlying form element. ```ts submit(form); ``` #### Parameters - `form` ##### Explanation The `form` parameter is the form store to submit. The function triggers form submission by calling the native `requestSubmit()` method on the underlying form element. #### Related ##### Primitives ##### Methods ### swap Swaps two items in a field array at the specified indices. ```ts swap(form, config); ``` #### Generics - `TSchema` - `TFieldArrayPath` #### Parameters - `form` - `config` ##### Explanation The `form` parameter is the form store containing the field array. The `config` parameter specifies the path to the field array and the two indices of the items to swap. #### Related ##### Primitives ##### Methods ### validate Validates the entire form input against its schema. Returns a safe parse result indicating success or failure with detailed issues. Optionally focuses the first field with validation errors. ```ts const result = validate(form, config?); ``` #### Generics - `TSchema` #### Parameters - `form` - `config` ##### Explanation The `form` parameter is the form store to validate. The optional `config` parameter allows specifying whether to automatically focus the first field with validation errors after validation. #### Returns - `result` #### Related ##### Primitives ##### Methods ## Types ### DeepPartial A utility type that recursively makes all properties and nested properties optional. > This type is too complex to display. Please refer to the [source code](https://github.com/open-circle/formisch/blob/main/packages/core/src/types/utils/utils.ts). #### Related ##### Primitives ### FieldArrayStore Reactive field array store interface with properties for managing array fields. #### Generics - `TSchema` - `TFieldArrayPath` #### Definition - `FieldArrayStore` - `path` - `items` - `errors` - `isTouched` - `isDirty` - `isValid` ### FieldElement A union type representing form field elements that can be registered with a field store. #### Definition - `FieldElement` #### Related ##### Methods ### FieldElementProps Props to spread onto a field element for integration with React form handling. #### Definition - `FieldElementProps` - `FieldElementProps` - `name` - `autoFocus` - `ref` - `onFocus` - `onChange` - `onBlur` ### FieldStore Reactive field store interface with properties and element props for field management. #### Generics - `TSchema` - `TFieldPath` #### Definition - `FieldStore` - `path` - `input` - `errors` - `isTouched` - `isDirty` - `isValid` - `onChange` - `props` ### FocusFieldConfig Configuration interface for focusing a field. Used by the `focus` method to specify which field to focus and any additional focus options. #### Generics - `TSchema` - `TFieldPath` #### Definition - `FocusFieldConfig` - `path` #### Related ##### Methods ### FormConfig Form config interface that defines the configuration options for creating a form store with `useForm`. #### Generics - `TSchema` #### Definition - `FormConfig` - `schema` - `initialInput` - `validate` - `revalidate` ##### Explanation The `FormConfig` object is passed to `useForm` with a required `schema` property and optional properties for `initialInput`, `validate`, and `revalidate` to control form behavior and validation timing. ### FormSchema Type definition that represents the Valibot object schemas allowed as the root of a form. This includes object schemas, combinators (`intersect`, `union`, `variant`) whose options resolve to objects, and `lazy` schemas wrapping any of these. Forms must have an object root; use Schema for nested field schemas. #### Definition - `FormSchema` #### Related ##### Primitives ##### Methods ### FormStore Form store interface that provides reactive access to the state of a form created with `useForm`. #### Generics - `TSchema` #### Definition - `FormStore` - `isSubmitting` - `isSubmitted` - `isValidating` - `isTouched` - `isDirty` - `isValid` - `errors` ##### Explanation The `errors` property only contains validation errors at the root level of the form. These are errors from the root object schema validation itself, not errors from nested fields. To retrieve all validation errors from all fields across the entire form, use the `getAllErrors` method instead. ### GetFieldDirtyInputConfig Configuration interface for retrieving field-scoped dirty input. Used by the `getDirtyInput` method when a specific field path is provided. #### Generics - `TSchema` - `TFieldPath` #### Definition - `GetFieldDirtyInputConfig` - `path` #### Related ##### Methods ### GetFieldDirtyPathsConfig Configuration interface for inspecting field-scoped dirty paths. Used by the `getDirtyPaths` method when a specific field path is provided. #### Generics - `TSchema` - `TFieldPath` #### Definition - `GetFieldDirtyPathsConfig` - `path` #### Related ##### Methods ### GetFieldErrorsConfig Configuration interface for retrieving field-specific errors. Used by the `getErrors` method when a specific field path is provided. #### Generics - `TSchema` - `TFieldPath` #### Definition - `GetFieldErrorsConfig` - `path` #### Related ##### Methods ### GetFieldInputConfig Configuration interface for retrieving field-specific input. Used by the `getInput` method when a specific field path is provided. #### Generics - `TSchema` - `TFieldPath` #### Definition - `GetFieldInputConfig` - `path` #### Related ##### Methods ### GetFormDirtyInputConfig Configuration interface for retrieving form-level dirty input. Used by the `getDirtyInput` method when no specific field path is provided. #### Definition - `GetFormDirtyInputConfig` - `path` #### Related ##### Methods ### GetFormDirtyPathsConfig Configuration interface for inspecting form-level dirty paths. Used by the `getDirtyPaths` method when no specific field path is provided. #### Definition - `GetFormDirtyPathsConfig` - `path` #### Related ##### Methods ### GetFormErrorsConfig Configuration interface for retrieving form-level errors. Used by the `getErrors` method when no specific field path is provided. #### Definition - `GetFormErrorsConfig` - `path` #### Related ##### Methods ### GetFormInputConfig Configuration interface for retrieving form-level input. Used by the `getInput` method when no specific field path is provided. #### Definition - `GetFormInputConfig` - `path` #### Related ##### Methods ### InsertConfig Configuration interface for inserting items into array fields. Used by the `insert` method. #### Generics - `TSchema` - `TFieldArrayPath` #### Definition - `InsertConfig` - `path` - `at` - `initialInput` #### Related ##### Methods ### PartialValues Utility type that recursively makes all value properties optional, including nested objects and arrays. #### Generics - `TValue` #### Definition - `PartialValues` #### Related ##### Methods ### Path Type definition for readonly arrays of path keys used to access nested properties. #### Definition - `Path` ### PathKey Type definition for keys used in paths to access nested properties in objects and arrays. #### Definition - `PathKey` ### PickDirtyConfig Configuration interface for picking dirty parts of a value. Used by the `pickDirty` method. #### Generics - `TValue` #### Definition - `PickDirtyConfig` - `from` #### Related ##### Methods ### MoveConfig Configuration interface for moving items within array fields. Used by the `move` method. #### Generics - `TSchema` - `TFieldArrayPath` #### Definition - `MoveConfig` - `path` - `from` - `to` #### Related ##### Methods ### RemoveConfig Configuration interface for removing items from array fields. Used by the `remove` method. #### Generics - `TSchema` - `TFieldArrayPath` #### Definition - `RemoveConfig` - `path` - `at` #### Related ##### Methods ### ReplaceConfig Configuration interface for replacing items in array fields. Used by the `replace` method. #### Generics - `TSchema` - `TFieldArrayPath` #### Definition - `ReplaceConfig` - `path` - `at` - `initialInput` #### Related ##### Methods ### RequiredPath A type that represents a required path into an object structure with at least one key. > This type is too complex to display. Please refer to the [source code](https://github.com/open-circle/formisch/blob/main/packages/core/src/types/path/path.ts). #### Related ##### Methods ### ResetFieldConfig Configuration interface for resetting field-specific input and errors. Used by the `reset` method when a specific field path is provided. #### Generics - `TSchema` - `TFieldPath` #### Definition - `ResetFieldConfig` - `path` - `initialInput` - `keepErrors` - `keepInput` - `keepTouched` #### Related ##### Methods ### ResetFormConfig Configuration interface for resetting form input and errors. Used by the `reset` method when no specific field path is provided. #### Generics - `TSchema` #### Definition - `ResetFormConfig` - `initialInput` - `keepErrors` - `keepInput` - `keepSubmitted` - `keepTouched` #### Related ##### Methods ### Schema Schema type definition that represents any Valibot schema that can be used with Formisch. #### Definition - `Schema` #### Related ##### Primitives ##### Methods ### SetFieldErrorsConfig Configuration interface for setting field-specific errors. Used by the `setErrors` method when a specific field path is provided. #### Generics - `TSchema` - `TFieldPath` #### Definition - `SetFieldErrorsConfig` - `path` - `errors` #### Related ##### Methods ### SetFieldInputConfig Configuration interface for setting field-specific input. Used by the `setInput` method when a specific field path is provided. #### Generics - `TSchema` - `TFieldPath` #### Definition - `SetFieldInputConfig` - `path` - `input` #### Related ##### Methods ### SetFormErrorsConfig Configuration interface for setting form-level errors. Used by the `setErrors` method when no specific field path is provided. #### Definition - `SetFormErrorsConfig` - `path` - `errors` #### Related ##### Methods ### SetFormInputConfig Configuration interface for setting form-level input. Used by the `setInput` method when no specific field path is provided. #### Generics - `TSchema` #### Definition - `SetFormInputConfig` - `path` - `input` #### Related ##### Methods ### SubmitEventHandler Function type for handling form submission with the submit event. Used by the `handleSubmit` method and form components. #### Generics - `TSchema` #### Parameters - `output` - `event` #### Related ##### Methods ##### Types ### SubmitHandler Function type for handling form submission without the submit event. Used by the `handleSubmit` method. #### Generics - `TSchema` #### Parameters - `output` #### Related ##### Methods ##### Types ### SwapConfig Configuration interface for swapping items in array fields. Used by the `swap` method. #### Generics - `TSchema` - `TFieldArrayPath` #### Definition - `SwapConfig` - `path` - `at` - `and` #### Related ##### Methods ### UseFieldArrayConfig Configuration object for creating a field array store with `useFieldArray`. #### Generics - `TSchema` - `TFieldArrayPath` #### Definition - `UseFieldArrayConfig` - `path` ### UseFieldConfig Configuration object for creating a field store with `useField`. #### Generics - `TSchema` - `TFieldPath` #### Definition - `UseFieldConfig` - `path` ### ValidArrayPath A utility type that validates array paths and returns the first possible valid array path based on the given value if the provided path is invalid. > This type is too complex to display. Please refer to the [source code](https://github.com/open-circle/formisch/blob/main/packages/core/src/types/path/path.ts). ### ValidateFormConfig Configuration interface for form validation. Used by the `validate` method to specify validation behavior. #### Definition - `ValidateFormConfig` - `shouldFocus` #### Related ##### Methods ### ValidationMode Validation mode type that defines when and how form validation is triggered. #### Definition - `ValidationMode` #### Related ##### Primitives ##### Methods