# @mwillbanks/tuil-form

Source: /tuil/docs/reference/packages/form
Locale: en

Typed form state, validation, and controlled field adapters for tuil.



## Overview [#overview]

Typed form state, validation, and controlled field adapters for tuil.

`@mwillbanks/tuil-form` is independently installable and also participates in the
umbrella `@mwillbanks/tuil` runtime where applicable.

## Installation [#installation]

<CodeBlockTabs defaultValue="npm">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npm install @mwillbanks/tuil-form
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm add @mwillbanks/tuil-form
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn add @mwillbanks/tuil-form
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun add @mwillbanks/tuil-form
    ```
  </CodeBlockTab>
</CodeBlockTabs>

## How it operates [#how-it-operates]

Form state coordinates field registration, values, touched and dirty state, sync or async validators, submission, reset, and framework adapters.

<Mermaid
  chart="flowchart LR
  S0[&#x22;register fields&#x22;]
  S1[&#x22;edit&#x22;]
  S2[&#x22;validate&#x22;]
  S3[&#x22;submit or reject&#x22;]
  S4[&#x22;reset/dispose&#x22;]
  S0 --> S1
  S1 --> S2
  S2 --> S3
  S3 --> S4"
/>

## API [#api]

| API                                                                                           | Signature                            | Description                                                                                                                                                                                                                                       |
| --------------------------------------------------------------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`AdaptedTanStackField`](/tuil/docs/reference/packages/form/api/adapted-tan-stack-field)           | `interface AdaptedTanStackField`     | Public interface AdaptedTanStackField.                                                                                                                                                                                                            |
| [`adaptTanStackField`](/tuil/docs/reference/packages/form/api/adapt-tan-stack-field)               | `function adaptTanStackField`        | Public function adaptTanStackField.                                                                                                                                                                                                               |
| [`createFormHook`](/tuil/docs/reference/packages/form/api/create-form-hook)                        | `export createFormHook`              | Public export createFormHook.                                                                                                                                                                                                                     |
| [`createFormHookContexts`](/tuil/docs/reference/packages/form/api/create-form-hook-contexts)       | `export createFormHookContexts`      | Public export createFormHookContexts.                                                                                                                                                                                                             |
| [`FieldValidator`](/tuil/docs/reference/packages/form/api/field-validator)                         | `type FieldValidator`                | Public type FieldValidator.                                                                                                                                                                                                                       |
| [`FieldValidators`](/tuil/docs/reference/packages/form/api/field-validators)                       | `interface FieldValidators`          | Public interface FieldValidators.                                                                                                                                                                                                                 |
| [`FormFieldRegistration`](/tuil/docs/reference/packages/form/api/form-field-registration)          | `interface FormFieldRegistration`    | Public interface FormFieldRegistration.                                                                                                                                                                                                           |
| [`formOptions`](/tuil/docs/reference/packages/form/api/form-options)                               | `export formOptions`                 | Public export formOptions.                                                                                                                                                                                                                        |
| [`FormValidationError`](/tuil/docs/reference/packages/form/api/form-validation-error)              | `interface FormValidationError`      | Public interface FormValidationError.                                                                                                                                                                                                             |
| [`TanStackFieldLike`](/tuil/docs/reference/packages/form/api/tan-stack-field-like)                 | `interface TanStackFieldLike`        | Public interface TanStackFieldLike.                                                                                                                                                                                                               |
| [`TerminalFieldBinding`](/tuil/docs/reference/packages/form/api/terminal-field-binding)            | `interface TerminalFieldBinding`     | Public interface TerminalFieldBinding.                                                                                                                                                                                                            |
| [`TerminalFieldController`](/tuil/docs/reference/packages/form/api/terminal-field-controller)      | `class TerminalFieldController`      | Public class TerminalFieldController.                                                                                                                                                                                                             |
| [`TerminalFieldOptions`](/tuil/docs/reference/packages/form/api/terminal-field-options)            | `interface TerminalFieldOptions`     | Public interface TerminalFieldOptions.                                                                                                                                                                                                            |
| [`TerminalFieldState`](/tuil/docs/reference/packages/form/api/terminal-field-state)                | `interface TerminalFieldState`       | Public interface TerminalFieldState.                                                                                                                                                                                                              |
| [`TerminalFormController`](/tuil/docs/reference/packages/form/api/terminal-form-controller)        | `class TerminalFormController`       | Public class TerminalFormController.                                                                                                                                                                                                              |
| [`TerminalFormProvider`](/tuil/docs/reference/packages/form/api/terminal-form-provider)            | `function TerminalFormProvider`      | Public function TerminalFormProvider.                                                                                                                                                                                                             |
| [`useForm`](/tuil/docs/reference/packages/form/api/use-form)                                       | `export useForm`                     | A custom React Hook that returns an extended instance of the `FormApi` class.  This API encapsulates all the necessary functionalities related to the form. It allows you to manage form state, handle submissions, and interact with form fields |
| [`useRegisterTerminalField`](/tuil/docs/reference/packages/form/api/use-register-terminal-field)   | `function useRegisterTerminalField`  | Public function useRegisterTerminalField.                                                                                                                                                                                                         |
| [`useStore`](/tuil/docs/reference/packages/form/api/use-store)                                     | `export useStore`                    | Public export useStore.                                                                                                                                                                                                                           |
| [`useTerminalField`](/tuil/docs/reference/packages/form/api/use-terminal-field)                    | `function useTerminalField`          | Public function useTerminalField.                                                                                                                                                                                                                 |
| [`useTerminalFormController`](/tuil/docs/reference/packages/form/api/use-terminal-form-controller) | `function useTerminalFormController` | Public function useTerminalFormController.                                                                                                                                                                                                        |
| [`useTerminalFormSnapshot`](/tuil/docs/reference/packages/form/api/use-terminal-form-snapshot)     | `function useTerminalFormSnapshot`   | Public function useTerminalFormSnapshot.                                                                                                                                                                                                          |
| [`ValidationContext`](/tuil/docs/reference/packages/form/api/validation-context)                   | `interface ValidationContext`        | Public interface ValidationContext.                                                                                                                                                                                                               |
| [`ValidationTrigger`](/tuil/docs/reference/packages/form/api/validation-trigger)                   | `type ValidationTrigger`             | Public type ValidationTrigger.                                                                                                                                                                                                                    |

## Events and lifecycle [#events-and-lifecycle]

State changes are subscription-based. UI controls expose `onValueChange`, `onSubmit`, and field-level callbacks.

All subscriptions and registrations return a disposer or belong to an owning
runtime that disposes them in reverse order.

## Example [#example]

```tsx
const form = createForm({ initialValues: { name: "" }, onSubmit: async (values) => save(values) });
```

## Related [#related]

* [Package architecture](/tuil/docs/concepts/packages)
* [Events](/tuil/docs/concepts/events)
* [Testing](/tuil/docs/guides/testing)