• English

      • Quick Reference Card

      A one-page cheat sheet covering the most commonly used APIs and patterns.

      Component Imports

      import { Form } from '@schema-formx/react';
import type {
  FieldSchema,
  GroupSchema,
  FormInstance,
  Layout,
  Components
} from '@schema-formx/react';

      Core Patterns

      <Form
  schema={schema}
  defaultData={{ name: 'John', age: 25 }}
  onChange={({ data }) => console.log(data)}
/>

      Controlled Mode

      const [formData, setFormData] = useState({ name: '', age: 0 });

<Form
  schema={schema}
  data={formData}
  onChange={({ data }) => setFormData(data)}
/>

      Form Instance Methods

      const formRef = useRef<FormInstance>(null);

// Get data
const data = formRef.current.getData();

// Set data
formRef.current.setData({ name: 'new value' });

// Validate form
const { data, errors } = await formRef.current.validate();

// Reset form
formRef.current.reset();

// Check if modified
const isDirty = formRef.current.isDirty();

      Field Configuration Reference

      FieldSchema

      type FieldSchema = {
  type?: 'string' | 'number' | 'boolean' | 'object' | 'array';
  name: string;          // Field name
  label: string;         // Display name
  required?: boolean;    // Required field
  component?: string;    // Custom component name
  props?: object;        // Component props
  hidden?: boolean;      // Hide field
  deps?: string[];       // Dependent fields
  onDepsChange?: Function; // Linkage callback
  validator?: Function;  // Validator
};

      Field Types & Defaults

      TypeDefaultEmpty Values
      string''null, undefined, ''
      numbernullnull, undefined, ''
      booleannullnull, undefined, ''
      object{}null, undefined, {}
      array[]null, undefined, []

      Group Configuration Reference

      GroupSchema

      type GroupSchema = {
  key: string;           // Unique group identifier
  fields: FieldSchema[]; // Fields in the group
  component?: string;    // Custom group container
  props?: object;        // Container props
};

      Usage Example

      const schema: GroupSchema[] = [
  {
    key: 'basic',
    props: { title: 'Basic Info' },
    fields: [
      { type: 'string', name: 'name', label: 'Name', required: true },
      { type: 'string', name: 'email', label: 'Email', required: true }
    ]
  }
];

      Layout Configuration Reference

      Layout

      type Layout = {
  // Form level
  formClassName?: string;
  formStyle?: CSSProperties;
  // Group level
  groupClassName?: string;
  groupStyle?: CSSProperties;
  // Field level
  fieldClassName?: string;
  fieldStyle?: CSSProperties;
  // Label level
  labelClassName?: string;
  labelStyle?: CSSProperties;
  // Tip level
  tipClassName?: string;
  tipStyle?: CSSProperties;
  // Control level
  controlClassName?: string;
  controlStyle?: CSSProperties;
  // Specific groups
  groups?: Record<string, { groupClassName?: string; groupStyle?: CSSProperties }>;
  // Specific fields
  fields?: Record<string, {
    fieldClassName?: string; fieldStyle?: CSSProperties;
    labelClassName?: string; labelStyle?: CSSProperties;
    controlClassName?: string; controlStyle?: CSSProperties;
    tipClassName?: string; tipStyle?: CSSProperties;
  }>;
};

      Usage Example

      const layout: Layout = {
  formStyle: { maxWidth: '600px', margin: '0 auto' },
  fieldStyle: { marginBottom: '16px' },
  labelStyle: { fontWeight: '500' },
  fields: {
    username: { controlStyle: { width: '300px' } }
  }
};

      Validation Rules Reference

      Built-in Validation

      { type: 'string', name: 'email', label: 'Email', required: true }

      Custom Validation

      {
  type: 'string',
  name: 'email',
  label: 'Email',
  validator: ({ value, label }) => {
    if (!value) return `${label} is required`;
    if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)) {
      return `${label} format is incorrect`;
    }
    return undefined; // Pass
  }
}

      Async Validation

      {
  type: 'string',
  name: 'username',
  label: 'Username',
  validator: async ({ value, label }) => {
    const exists = await checkUsername(value);
    return exists ? `${label} is already taken` : undefined;
  }
}

      Dependency Linkage Reference

      Basic Linkage

      {
  type: 'string',
  name: 'city',
  label: 'City',
  deps: ['province'],
  onDepsChange: async ({ deps, schema }) => {
    const cities = await getCities(deps[0]);
    return {
      patch: { city: '' },  // Clear city
      schema: { ...schema, props: { options: cities } }
    };
  }
}

      Return Value

      ReturnPurposeDescription
      patchUpdate form dataShallow merge into current data
      schemaUpdate field configComplete replacement of current field schema

      Component Registration Reference

      const components: Components = {
  DefaultControl: MyInput,    // Default control (required)
  DefaultGroup: MyGroup,      // Default group container (optional)
  ColorPicker: ColorPicker,   // Custom component
};

<Form schema={schema} components={components} />

      Component Lookup Order

      1. components[component] → Custom registered component
      2. components['DefaultControl'] → Default control
      3. Error "error component"

      Group Container Lookup Order

      1. GroupSchema.component → Group-specific component
      2. components['DefaultGroup'] → Default group container
      3. Built-in Group component