useFormCopy Anchor Link

useForm(options) returns a UseFormReturn<Values, Level> with the core FormApi methods. Call it inside a React component or custom hook. Values are inferred from schema; defaultValues must match that type. Issue levels are inferred from checks, with error always included.

import { useForm } from '@oxform/react';
import { z } from 'zod';

function EmailForm() {
  const form = useForm({
    schema: z.object({ email: z.string() }),
    defaultValues: { email: '' },
  });

  return (
    <button type='button' onClick={() => form.reset()}>
      Reset
    </button>
  );
}

OptionsCopy Anchor Link

Updated options are used by later validation and resets. Updating defaultValues changes the reset baseline without replacing current values. Call reset() to apply it.

PropertiesCopy Anchor Link

field and array operate on the same state as useField and useArrayField. Their first argument is the path; the remaining arguments match the corresponding bound API method. form.field.status(name) reads status; bound field APIs expose it as field.state.status. form.field.register(name) returns an element callback.

import { useForm } from '@oxform/react';
import { z } from 'zod';

function Actions() {
  const form = useForm({
    schema: z.object({ email: z.string(), tags: z.array(z.string()) }),
    defaultValues: { email: '', tags: [] },
  });

  return (
    <button
      type='button'
      onClick={() => {
        form.field.change('email', 'ada@example.com');
        form.array.append('tags', 'customer');
      }}
    >
      Fill
    </button>
  );
}

validate(fields?, options?)Copy Anchor Link

Returns Promise<[boolean, FormIssuesByLevel<Level>]>. Omit fields for the whole form, pass a path for its subtree, or pass an array of paths. options.type selects change, blur, focus, or submit; omitting it runs the root schema and all configured events.

The boolean describes blocking issues emitted by this run. form.status.valid describes all current issues. The returned issue buckets contain issues emitted for the requested targets. See Validation for replacement and async behavior.

const [valid, issues] = await form.validate('email', { type: 'blur' });
await form.validate(['email', 'profile']);
await form.validate();

submit(onSuccess, onError?)Copy Anchor Link

Returns a zero-argument () => Promise<void> handler. It validates the whole form for submit and calls one callback, awaiting it. onSuccess(values, form) runs only when the validation result and aggregate current validity both pass. onError(issues, form) receives all current form issues.

import { useForm } from '@oxform/react';
import { z } from 'zod';

function SignupForm() {
  const form = useForm({ schema: z.object({ email: z.email() }), defaultValues: { email: '' } });
  const submit = form.submit(
    values => {
      console.info(values.email);
    },
    issues => {
      console.error(issues.error);
    },
  );

  return (
    <form
      onSubmit={event => {
        event.preventDefault();
        void submit();
      }}
    >
      <button type='submit' disabled={form.status.submitting}>
        Submit
      </button>
    </form>
  );
}

The handler sets dirty and submitting before validation. After the callback resolves, it increments submits, clears submitting, and records successful. A rejected validator or callback rejects the handler; these completion updates are not guaranteed after a rejection. The handler does not prevent browser submission or suppress concurrent calls.

reset(options?)Copy Anchor Link

Restores defaultValues, clears issues and refs, recreates field state, and resets submit status. options.values supplies a different full values object for this reset without changing defaultValues. options.status overrides the reset form status.

keep.issues: true keeps all issues, or an array of levels keeps only those levels. keep.refs retains element references. keep.fields retains complete field state, including IDs, status, refs, and issues, and takes precedence over the other field preservation flags. Preservation of issues and refs applies to paths that remain after reset.

form.reset();
form.reset({ keep: { refs: true, issues: ['error'] } });
form.reset({ values: { email: 'ada@example.com' }, status: { submits: 0 } });

Adapter LifecycleCopy Anchor Link

form['~mount']() returns a cleanup function. form['~update'](options) updates configuration without resetting values. React manages these calls. They are exposed for adapter authors.

SignaturesCopy Anchor Link