npm package: @kittlekit/schema-form-react
Description: React orchestration layer for bootstrap schema forms
Latest version: 0.1.2

# @kittlekit/schema-form-react

[![npm version](https://img.shields.io/npm/v/@kittlekit/schema-form-react.svg)](https://www.npmjs.com/package/@kittlekit/schema-form-react)
[![license: MIT](https://img.shields.io/badge/license-MIT-green.svg)](../../LICENSE)

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

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

## Quick Start

```tsx
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

```text
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

```bash
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