API reference

Everything below is exported from the package root, reactformswitch.

`<FormSwitch>`

interface FormSwitchProps {
  schema: FormSchema
  /** Legacy theme prop; schema.ui.theme supersedes it. */
  theme?: 'light' | 'dark' | ThemeTokens
  className?: string
  onSubmit: (payload: unknown, values: Values) => void | Promise<void>
}

onSubmit receives the serialized payload and the raw values. It may be async — the submit button shows a loader while the promise is pending. With an image field on a json / xml payload it is always async.

FormSchema

interface FormSchema {
  fields?: FieldSpec[]   // single-page form
  steps?: StepSpec[]     // multi-step; presence switches on the wizard UI
  payload?: PayloadFormat
  submitLabel?: string
  loader?: string        // loader shown on the submit button
  ui?: UIConfig          // JSON-authored look & behavior
}

interface StepSpec { title?: string; fields: FieldSpec[] }

fields and steps are mutually exclusive.

FieldSpec

interface FieldSpec {
  name: string                       // becomes the value key
  type: string                       // field registry key: "text", "select", …
  label?: string
  placeholder?: string
  size?: string                      // preset or any CSS length
  options?: { label: string; value: string }[]   // select / radio
  validation?: ZodTypeAny            // Zod validator (wins over rules)
  rules?: FieldRules                 // JSON validation
  defaultValue?: unknown
  col?: number | { mobile?: number; tablet?: number; desktop?: number }
  showIf?: (values: Values) => boolean

  // image field (type: "image")
  accept?: string[]                  // allowed MIME types
  maxSizeMB?: number                 // per-file size cap
  maxFiles?: number                  // omit or 1 for a single image
  required?: boolean                 // require at least one file
}

interface FieldRules {
  required?: boolean
  email?: boolean
  pattern?: string                   // regex source string
  minLength?: number; maxLength?: number
  min?: number; max?: number         // numeric bounds
  message?: string                   // custom error text for any failed rule
}

payload

PayloadFormat = 'json' | 'formdata' | 'xml' or any name you register. Defaults to json.

UIConfig

The JSON-authored look & behavior — see Look & behavior for the full shape and allowed values (UITheme, UIButton, UIToast, FieldSize, LabelPosition, ButtonPosition, ErrorDisplay, ToastPosition are all exported).

Functions

Export	Purpose
`registerField(type, Component)` / `getField` / `hasField`	custom field types
`registerSerializer(name, fn)` / `serialize(name, values)`	custom payloads
`registerLoader(name, Component)` / `getLoader` / `Loader`	loaders
`defineTheme(...tokens)`	merge `--fs-*` token objects
`themes`, `light`, `dark`	built-in theme presets

FieldProps

The props every registered field component receives — headless and controlled:

interface FieldProps {
  spec: FieldSpec
  id: string
  value: unknown
  onChange: (value: unknown) => void
  onBlur: () => void
  error?: string
}

Types

Also exported: FieldComponent, LoaderComponent, Serializer, ThemeInput, ThemeTokens, ColSpan, Option, Values.

On this page