@kittlekit/schema-form-react

React orchestration layer for Kittlekit schema forms. This package connects @kittlekit/schema-form-core to React and @tanstack/react-form without forcing a specific visual renderer.

What This Package Is

Use this package when you want:

• schema-driven React form state
• submit orchestration
• field transformation and validation hooks
• a reusable form engine that can power a custom renderer

This package is intentionally lighter than @kittlekit/schema-form-tailwind. It gives you orchestration, not a complete visual theme.

Install

npm install @kittlekit/schema-form-react @kittlekit/schema-form-core react react-dom zod @tanstack/react-form

Quick Start

import * as React from "react"
import { z } from "zod"
import { fieldMeta } from "@kittlekit/schema-form-core"
import { useSchemaForm } from "@kittlekit/schema-form-react"

const schema = z.object({
  name: z.string().describe(fieldMeta({ label: "Name" })),
  email: z.string().email().describe(fieldMeta({ label: "Email" })),
})

export function UserForm() {
  const { fields, form, submit } = useSchemaForm({
    schema,
    onSubmit: async (data) => {
      console.log(data)
    },
  })

  return (
    <form
      onSubmit={async (event) => {
        event.preventDefault()
        await submit()
      }}
    >
      {fields.map((field) => (
        <form.Field key={field.name} name={field.name}>
          {(instance) => (
            <input
              value={String(instance.state.value ?? "")}
              onChange={(event) => instance.handleChange(event.target.value)}
            />
          )}
        </form.Field>
      ))}
      <button type="submit">Submit</button>
    </form>
  )
}

Main Export

useSchemaForm(options)

Provides:

• fields
• form
• defaultValues
• submit()
• submitError
• setSubmitError()

Supported options

• schema
• defaultValues
• formKey
• onSubmit
• beforeSubmit
• validate
• transformFields

These make it possible to customize orchestration without forking core logic.

Extension Points

transformFields

Use when you want to reorder, hide, or inject fields after Zod parsing.

validate

Use when you want domain validation in addition to Zod validation.

beforeSubmit

Use when you need final payload transformation before the validated submit step.

Typical Architectures

Headless React form

Use useSchemaForm plus your own renderer.

UI kit integration

Use useSchemaForm plus your design system components.

With Kittlekit Tailwind renderer

If you want the full prebuilt renderer, use @kittlekit/schema-form-tailwind on top of this package.

Relationship to Other Packages

schema-form-core -> schema-form-react -> schema-form-tailwind

Out of Scope

This package intentionally does not include:

• Tailwind styling
• upload widgets
• map widgets
• Next.js-only behavior
• app-specific fetch logic

Runtime Notes

• React-only package
• uses @tanstack/react-form
• ESM package with runtime JS + type definitions

Publish

npm run build --workspace @kittlekit/schema-form-react
npm publish --workspace @kittlekit/schema-form-react --access public

Examples

• smoke app: sandbox/schema-form-smoke
• app integration: web/src/components/form/SchemaForm.tsx

Release Notes

0.1.1

• exposed stable React orchestration on top of schema-form-core
• validated submit lifecycle and package consumption from npm