useFieldCopy Anchor Link

useField({ form, name }) returns a reactive field API and controlled-input props. name is a schema-derived field path, and the value type follows that path.

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

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

  return <input {...email.props} />;
}

OptionsCopy Anchor Link

form is the owning form API. name selects a path, including parent objects and array item paths such as 'contacts.0.email'. There is no field-specific schema option; configure validators on the form.

PropertiesCopy Anchor Link

state.defaultValue is the value at this path in the current form defaults. state.ref is the registered HTMLElement or null. Issues are grouped by level and include error plus configured levels, even when their arrays are empty. Field status is described in Status.

Input PropsCopy Anchor Link

These bindings read value, not checked, and do not convert strings into numbers. Use explicit handlers for checkboxes, numeric inputs, file inputs, and custom controls.

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

function Preferences() {
  const form = useForm({ schema: z.object({ enabled: z.boolean() }), defaultValues: { enabled: false } });
  const enabled = useField({ form, name: 'enabled' });

  return (
    <input
      type='checkbox'
      ref={enabled.register}
      checked={enabled.state.value}
      onChange={event => enabled.change(event.target.checked)}
      onBlur={() => enabled.blur()}
      onFocus={() => enabled.focus()}
    />
  );
}

MethodsCopy Anchor Link

get()Copy Anchor Link

Returns the current value without changing status or running validation.

const emailValue = email.get();

change(valueOrUpdater, options?)Copy Anchor Link

Accepts a direct value or (current: Value) => Value. Updates the bound value and marks it and its ancestor fields dirty and touched by default. Sibling values are unchanged. Changing a parent does not mark descendant status.

should.dirty: false and should.touch: false preserve the corresponding status instead of clearing it. Validation runs for change when any level has a change validator. should.validate: false skips it; true requests the event explicitly. This method returns void; use await form.validate(name, { type: 'change' }) when completion is needed.

email.change('ada@example.com');
email.change(current => current.trim());
email.change('', { should: { dirty: false, touch: false, validate: false } });

focus(options?) and blur(options?)Copy Anchor Link

focus focuses a registered element and marks the field and ancestors touched. blur blurs the element and marks the field and ancestors blurred. These status updates also work without a registered element.

Each operation requests its matching validation event when configured. should.validate overrides that default. Both return void.

email.focus();
email.blur({ should: { validate: false } });

register(element) and unregister()Copy Anchor Link

Register an HTMLElement for focus and blur operations. Registering null has no effect. unregister() clears the reference without changing the value.

email.register(document.querySelector('input'));
email.unregister();

issues(options?)Copy Anchor Link

Reads issues for the bound path. { nested: true } includes descendant paths. state.issues contains only the bound path's issues.

const directIssues = email.issues();
const profileIssues = profile.issues({ nested: true });

setIssues(issues, options?)Copy Anchor Link

Accepts partial level buckets. replace is the default and replaces all buckets for this field, including omitted levels. append adds entries. keep retains all existing buckets if any existing bucket is nonempty; otherwise it writes the input. It is not a per-level merge.

email.setIssues({
  error: [{ level: 'error', issue: { message: 'Address already registered', path: ['email'] } }],
});
email.setIssues({ error: [] });
email.setIssues({ warning: [] }, { mode: 'append' });

Issue entries include level, issue, and optional event type. Error issues always block validity. Custom levels block only when configured. See Validation for how later validation replaces them.

reset(options?)Copy Anchor Link

Restores the bound value to its default, or to a non-nullish options.value. Clears issues and refs and restores default field status for the path and descendants. Sibling values are unchanged. It does not change the form's defaults or submit counter.

The current signature accepts status and keep on field reset options, but the current API does not apply those options. Use the form-level reset preservation options when needed.

email.reset();
email.reset({ value: 'ada@example.com' });

useFieldApiCopy Anchor Link

useFieldApi({ form, name }) returns the imperative FieldApi with the same operations and schema-derived types. It does not subscribe the component to field state and does not add props. Pair it with useSubscribe for selected state.

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

function EmailFeedback() {
  const form = useForm({ schema: z.object({ email: z.string() }), defaultValues: { email: '' } });
  const email = useFieldApi({ form, name: 'email' });
  const value = useSubscribe(email, state => state.value);

  return <span>{value}</span>;
}

FieldCopy Anchor Link

Field accepts form, name, and children. A render function receives the full useField return value. Static React children are also accepted. It does not add a DOM wrapper.

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

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

  return (
    <Field form={form} name='email'>
      {field => <input {...field.props} />}
    </Field>
  );
}

Adapter LifecycleCopy Anchor Link

field['~mount']() returns cleanup. field['~update']({ form, name }) updates the binding. React handles these calls.

SignaturesCopy Anchor Link