# useForm

Owns a form's values, validation, submit and errors in a machine. Field errors show once a field is touched; submit touches every field, waits for pending async checks and focuses the first invalid control.

## Use for

- a form: values, validation, submit, field errors, success UI
- a server check on a field as the user types, with `validateAsync`
- Clerk errors from a save landing on form fields

## Practices

- Do: Reject `onSubmit` with `FormSubmitError` (exported from this unit), or use `save` in the model, so errors land on fields and the banner.
- Do: Use `onSuccess` for success UI that stays mounted, such as a done step.
- Do: Spread `register(name)` on an `onChange` control and `registerValue(name)` on an `onValueChange` one.
- Do: Pass `form` whole to the view.
- Don't: Wrap `onSubmit` in `try`/`catch`. Reject, and the form shows why.
- Don't: Track a submitting flag in `useState`. Read `isSubmitting`.

## Options

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `initialValues` | `TValues` |  | The starting values, and the baseline `isDirty` compares against until `reset(values)`. |
| `fields` | `FieldsConfig<TValues>` |  | Per-field `validate` and `validateAsync`, each returning feedback or `undefined`. |
| `onSubmit` | `(values: TValues) => Promise<TResult>` |  | Runs with the values when the form is valid. Reject to show the error. |
| `onSuccess` | `(result: TResult, submittedValues: TValues) => void` |  | Called with the result and the submitted values after `onSubmit` resolves. |
| `canSubmit` | `(values: TValues) => boolean` | `always true` | An extra check on the values before submit is allowed. |
| `errorFallback` | `string` | `the generic form error` | Copy shown when the submit fails without an error the form can describe. |

## Returns

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  | A stable id. Pass it to the `Form` and to a `SubmitButton form` outside it. |
| `values` | `TValues` |  | The current values. |
| `fields` | `Record<keyof TValues, FormField>` |  | Per field: `feedback`, `isValidating`, `touched` and `isDirty`. |
| `error` | `string` |  | Form-level copy for the last failed submit, for `Card.Banner`. |
| `isSubmitting` | `boolean` |  | Whether a submit is queued behind async checks or running. |
| `isDirty` | `boolean` |  | Whether any value differs from its initial value. |
| `canSubmit` | `boolean` |  | Whether every field is valid and `canSubmit` passes. |
| `register` | `<K extends TextFieldName<TValues>>(name: K) => RegisteredField<TValues, K>` |  | Props for a string field on a control that takes `onChange(event)`. |
| `registerValue` | `<K extends keyof TValues>(name: K) => RegisteredValueField<TValues, K>` |  | Props for a field of any type on a control that takes `onValueChange(value)`. |
| `setValue` | `<K extends keyof TValues>(name: K, value: TValues[K]) => void` |  | Sets one value, clearing its submit error and starting its async check. |
| `touch` | `(name: keyof TValues) => void` |  | Marks a field touched, so its error shows. |
| `submit` | `() => void` |  | Submits, or focuses the first invalid control. |
| `handleSubmit` | `(event: { preventDefault: () => void }) => void` |  | A `<form>` submit handler: prevents the default, then submits. |
| `reset` | `(values?: TValues) => void` |  | Clears touched state and errors and resets to the initial values, or to `values`, which become the new baseline. |

## Examples

### A form in a view

```tsx
<Form id={form.id} onSubmit={form.handleSubmit}>
  <Card.Banner color='negative'>{form.error}</Card.Banner>
  <Field.Root invalid={form.fields.email.feedback?.type === 'error'}>
    <Field.Label>{m.email}</Field.Label>
    <Input {...form.register('email')} />
    <Field.Feedback feedback={form.fields.email.feedback} />
  </Field.Root>
  <SubmitButton isPending={form.isSubmitting} disabled={!form.canSubmit}>
    {m.save}
  </SubmitButton>
</Form>
```

## Related

- [Field](/docs/components/field.md)
- [Form](/docs/primitives/form.md)
- `SubmitButton`
- [Card](/docs/components/card.md)
