effect-view/packages/effect-view/ai-docs/MutationForm.md

MutationForm

A root form (implements Form.Form, see Form.md) that owns a local encoded draft and passes the valid decoded value to a Mutation when submit runs. Use for registration, checkout, search — any workflow with an explicit submit action.

import { Effect } from "effect"
import { Component, MutationForm, View } from "effect-view"

const form = yield* Component.useOnMount(() =>
  MutationForm.make({
    schema: ProfileSchema,
    initialEncodedValue: { displayName: "", age: "", contact: { email: "" } },
    f: ([profile, form]) => Effect.log(`Creating ${profile.displayName}, age ${profile.age}`),
  }).pipe(MutationForm.thenRun),
)

const [canCommit, isCommitting] = yield* View.useAll([form.canCommit, form.isCommitting])
const runPromise = yield* Component.useRunPromise()

<button disabled={!canCommit || isCommitting} onClick={() => void runPromise(form.submit)}>
  {isCommitting ? "Creating..." : "Create profile"}
</button>

• MutationForm.make({ schema, initialEncodedValue, f }) constructs the form; the underlying Mutation's input key is the tuple [decodedValue, form], not just the decoded value. Most f implementations only destructure the first element (profile.age is a number even though the input edited a string); form is included so f can, if needed, read other form state (e.g. form.issues, form.encodedValue) while handling the submission. MutationForm.thenRun starts initial validation in the current scope.
• Create once and keep stable — the usual home is Component.useOnMount.
• form.submit runs the mutation only when the form can currently commit; schema issues block submission before the mutation ever runs.
• Focus into subforms/fields with Form.focusObjectOn/focusArrayAt/etc. (see Form.md) and bind them to inputs with Form.useInput.
• If f fails with a Schema.SchemaError, form.submit formats that error into form.issues automatically — the same formatting path used for client-side decoding errors — instead of only surfacing it as a mutation failure. Any other failure from f is left as the mutation's Failure and does not touch form.issues.

Example: schema-owned date conversion

class DateTimeUtcFromZoned extends Schema.transformOrFail(Schema.DateTimeZonedFromSelf, Schema.DateTimeUtcFromSelf, {
  strict: true,
  decode: input => ParseResult.succeed(DateTime.toUtc(input)),
  encode: DateTime.setZoneCurrent,
}) {}

export class DateTimeUtcFromZonedInput extends Schema.transformOrFail(Schema.String, DateTimeUtcFromZoned, {
  strict: true,
  decode: (input, _options, ast) => Effect.flatMap(DateTime.CurrentTimeZone, timeZone =>
    Option.match(DateTime.makeZoned(input, { timeZone, adjustForTimeZone: true }), {
      onSome: ParseResult.succeed,
      onNone: () => ParseResult.fail(new ParseResult.Type(ast, input, "Enter a valid date and time")),
    })),
  encode: value => ParseResult.succeed(DateTime.formatIsoZoned(value).slice(0, 16)),
}) {}

An <input type="datetime-local"> edits "2026-07-22T14:30"; the schema decodes it to a UTC DateTime.Utc (decode(...).pipe requires DateTime.CurrentTimeZone — provide DateTime.layerCurrentZoneLocal in the runtime) and the mutation receives the UTC instant directly. No manual date parsing in the component.