AutoForm Documentation

AutoForm is a four-layer system. To avoid import errors, follow these layer boundaries:

1. Core Layer (@autoform/core): Contains types and utilities. Rarely imported directly.
2. Schema Provider Layer (@autoform/zod, @autoform/yup, or @autoform/joi): Handles parsing, validation, and fieldConfig.
3. React Adapter Layer (@autoform/react): Provides shared React contracts and implementations for React Hook Form or TanStack Form.
4. UI Library Layer (@autoform/mui, @autoform/mantine, @autoform/ant, @autoform/chakra, or shadcn/ui): Provides pre-wired UI components.

Critical Import Rules

• AutoForm Component: Import from the specific UI adapter path (e.g., @autoform/mui/react-hook-form or @autoform/mui/tanstack-form). For shadcn, use your local path: @/components/ui/autoform/react-hook-form.
• Schema Providers: Import the provider and fieldConfig from the matching schema package (e.g., ZodProvider from @autoform/zod).
• Shared Types: Import AutoFormFieldProps, FieldWrapperProps, etc., from @autoform/react.
• Custom Field Binding: Use useController from react-hook-form OR useFieldContext from @autoform/react/tanstack-form. Do not mix them.

AutoForm is structured in four distinct layers to allow flexibility between schema libraries and UI frameworks:

1. @autoform/core: The foundation. It is agnostic to schemas and UI, providing core types, interfaces, utility functions for parsing/validation, and a dependency manager for form fields.
2. Schema Providers (e.g., @autoform/zod): Adapts specific schema libraries (Zod, Yup, Joi) to AutoForm by implementing the SchemaProvider interface. They handle schema parsing, validation logic, and default values.
3. @autoform/react: Provides React context, contracts, and adapter-agnostic hooks. It exposes specific runtime implementations via subpaths: @autoform/react/react-hook-form and @autoform/react/tanstack-form.
4. UI-specific libraries (e.g., @autoform/mui): The final layer that provides themed components (inputs, selects, etc.) and wraps the selected @autoform/react adapter path.

Typical Workflow: Define schema $\rightarrow$ Pass to Schema Provider $\rightarrow$ Use UI-specific AutoForm component $\rightarrow$ Core parses schema and generates fields $\rightarrow$ UI components render fields and handle input $\rightarrow$ Validated data is passed to onSubmit.

Because AutoForm wraps the form with React Hook Form's FormProvider, components rendered as children of <AutoForm> can access form methods and state using useFormContext from react-hook-form without needing to pass a control object manually.

Data/State Read Methods Reference

import { useFormContext } from "react-hook-form";

function QuickActions() {
  const {
    watch,
    setValue,
    reset,
    formState: { isValid },
  } = useFormContext();
  // ...
}

AutoForm supports several advanced form patterns. Depending on your chosen form engine (React Hook Form or TanStack Form), you can implement:

• Real-time validation: Live errors, valid form state, and conditional submit button enabling.
• Dialog submit/reset: Handling form submission and resetting from buttons located outside the form component.
• Custom fields: Implementing sliders, color pickers, date pickers, file uploads, or radio cards. For components that must own the field value, use fieldConfig({ fieldType }) combined with formComponents instead of simple wrappers.
• Dependent/conditional fields: Cascading selects, showing/disabling/resetting UI based on other field values (watching fields).
• Multi-step forms: Wizards using multiple schemas, step-wise validation, and collecting data across steps.
• Nested AutoForm: Rendering a second AutoForm inside a custom field (e.g., for object editors or subforms in dialogs) and writing its submitted value to the parent field.
• Dynamic schema playground: Parsing schema strings (e.g., from a Monaco editor) to render AutoForm dynamically.

If you need to trigger submit, reset, or setFieldValue from components located outside the <AutoForm> tree (e.g., a Dialog footer), use the useAppForm hook.

Important:

• Pass the result of useAppForm to the formControl prop of AutoForm.
• Keep the options passed to useAppForm stable (use formOptions or useMemo) to avoid issues.
• Pass initial values via the defaultValues prop on AutoForm, not inside the formOptions object.

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

// Keep options stable
const staticOptions = formOptions({});

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

  return (
    <>
      <AutoForm
        schema={schemaProvider}
        formControl={form}
        defaultValues={{ username: "" }}
      />
      <button type="button" onClick={() => void form.handleSubmit()}>
        Submit
      </button>
    </>
  );
}