API

For shared source definitions, see packages/react/src/types.ts. For the TanStack adapter, see packages/react/src/tanstack-form.

AutoFormProps

UI integrations such as @autoform/mui, @autoform/ant, etc. provide default uiComponents and formComponents, while still allowing you to override them.

schema

schema must be a schema provider instance from one of the schema packages.

import { ZodProvider } from "@autoform/zod";
import * as z from "zod";

const schema = z.object({
  username: z.string(),
});

<AutoForm schema={new ZodProvider(schema)} withSubmit />;

defaultValues vs values

Use defaultValues for the initial form state. Use values only when the form should react to external state changes.

<AutoForm schema={schemaProvider} defaultValues={{ username: "johndoe" }} />

const [user, setUser] = useState({ username: "johndoe" });

<AutoForm schema={schemaProvider} values={user} />;

For TanStack Form, values is synchronized into the current form with setFieldValue. This is useful for controlled external state, but defaultValues is simpler when you only need initial values.

formControl

Use formControl when a parent component needs direct access to TanStack Form methods and state. Create it with useAppForm from @autoform/react/tanstack-form.

import { formOptions } from "@tanstack/react-form";
import { useAppForm } from "@autoform/react/tanstack-form";

const options = formOptions();

function MyForm() {
  const form = useAppForm(options);

  return (
    <>
      <AutoForm schema={schemaProvider} formControl={form} />
      <button onClick={() => form.reset()}>Reset</button>
    </>
  );
}

You can add options to useAppForm, like validationLogic, listeners, transforms, async settings, and validators. AutoForm adds its schema validator, default revalidation logic, and invalid-field focus behavior only where the external form did not provide an equivalent option.

When options depend on props or local values, memoize them with useMemo before passing them to useAppForm, or define them at module scope when they are static.

formComponents

formComponents maps AutoForm field types to React components. It is the right extension point for custom inputs.

import * as z from "zod";
import { fieldConfig, ZodProvider } from "@autoform/zod";

const schema = z.object({
  bio: z.string().check(fieldConfig({ fieldType: "markdown" })),
  favoriteColor: z.string().check(fieldConfig({ fieldType: "colorPicker" })),
});

const schemaProvider = new ZodProvider(schema);

<AutoForm
  schema={schemaProvider}
  formComponents={{
    markdown: MarkdownEditor,
    colorPicker: ColorPickerInput,
  }}
/>;

uiComponents

uiComponents replaces structural pieces such as wrappers, error messages, and the submit button. It is the right extension point for layout and design-system integration.

<AutoForm
  schema={schemaProvider}
  uiComponents={{
    FieldWrapper: CustomFieldWrapper,
    ErrorMessage: ({ error }) => <span className="text-red-500">{error}</span>,
  }}
/>

FieldWrapper, ObjectWrapper, ArrayWrapper, and ArrayElementWrapper can also be overridden per schema field through fieldConfig. The field-level wrapper has higher priority than the wrapper passed through uiComponents.

fieldConfig

fieldConfig is imported from your schema package and attached to individual schema fields.

Custom fields

Custom field components receive AutoFormFieldProps. Use useFieldContext from @autoform/react/tanstack-form to connect custom inputs to the TanStack field API.

import type { AutoFormFieldProps } from "@autoform/react";
import { useFieldContext } from "@autoform/react/tanstack-form";

export function StringField({ id, inputProps }: AutoFormFieldProps) {
  const field = useFieldContext<string>();

  return (
    <input
      id={id}
      name={field.name}
      value={field.state.value ?? ""}
      onBlur={field.handleBlur}
      onChange={(event) => field.handleChange(event.target.value)}
      {...inputProps}
    />
  );
}

TanStack adapter exports

import {
  AutoForm,
  useAppForm,
  useFormContext,
  useFieldContext,
} from "@autoform/react/tanstack-form";

Use UI package subpaths for rendered forms:

import { AutoForm } from "@autoform/mui/tanstack-form";

UI components

These components are used by the base renderer to assemble the form. Override them when you want to change layout, labels, error placement, object sections, array controls, or submit behavior.