# @cleverbrush/react-form
[](https://github.com/cleverbrush/framework/actions/workflows/ci.yml)
[](../../LICENSE)
A headless, schema-driven form system for React based on `@cleverbrush/schema`. Uses PropertyDescriptors for type-safe field binding, supports global UI renderer configuration via a provider, and is completely UI-agnostic — works with plain HTML, MUI, Ant Design, or any component library.
## Why @cleverbrush/react-form?
**The problem:** Every popular React form library — React Hook Form, Formik, React Final Form — requires you to reference fields by **string names**: `register("email")`, ``. The moment you pass a field name as a string, you lose TypeScript's type safety. Rename a property in your data model and the compiler stays silent — your form just silently breaks at runtime. The larger your codebase, the more of these invisible string references you accumulate, and the more fragile every refactor becomes.
```tsx
// React Hook Form — field names are plain strings
const { register } = useForm();
// ← no compiler error if "name" is renamed
// ← typo: silently fails at runtime
// Formik — same problem
// ← rename "city" → "town" and nothing warns you
```
**The solution:** `@cleverbrush/react-form` binds fields via **PropertyDescriptor selectors** — actual TypeScript expressions like `(t) => t.address.city` — instead of strings. The compiler knows the exact shape of your schema, so a renamed or mistyped property is a **compile-time error**, not a runtime surprise. On top of that, the schema **IS** the validation, the type definition, **AND** the form field configuration. One source of truth.
```tsx
// @cleverbrush/react-form — fully type-safe selectors
t.name} form={form} /> // ✓ checked at compile time
t.address.city} form={form} /> // ✓ rename "city" → compiler error
t.emial} form={form} /> // ✗ compile error: "emial" doesn't exist
```
**What makes it different:**
| Feature | @cleverbrush/react-form | React Hook Form | Formik | React Final Form |
| --- | --- | --- | --- | --- |
| Schema-driven validation | ✓ built-in | ~ via resolver | ~ via plugin | ✗ |
| Single source of truth (types + validation) | ✓ | ✗ | ✗ | ✗ |
| Type-safe field selectors | ✓ | ~ | ✗ | ✗ |
| Headless / UI-agnostic | ✓ | ✓ | ~ | ✓ |
| Global renderer system | ✓ | ✗ | ✗ | ✗ |
| Auto-field rendering by type + variant | ✓ | ✗ | ✗ | ✗ |
| Nested objects | ✓ | ✓ | ✓ | ✓ |
| Async validation | ✓ | ✓ | ✓ | ✓ |
## Installation
```bash
npm install @cleverbrush/react-form
```
**Peer dependencies:** `react >=18`, `@cleverbrush/schema ^2.0.0`
## Quick Start
```tsx
import { object, string, number } from '@cleverbrush/schema';
import { useSchemaForm, FormSystemProvider, Field } from '@cleverbrush/react-form';
// 1. Define schema — reuse across forms, API validation, mapping, etc.
const ContactSchema = object({
name: string().required('Name is required').minLength(2, 'Name must be at least 2 characters'),
email: string().required('Email is required'),
age: number().required('Age is required').min(18, 'Must be at least 18')
});
// 2. Define renderers once per app — maps schema types to UI components
const renderers = {
string: ({ value, onChange, onBlur, error, touched }) => (
)
};
// 3. Each form component only picks which fields to show — no boilerplate
function ContactForm() {
const form = useSchemaForm(ContactSchema);
const handleSubmit = async () => {
const result = await form.submit();
if (result.valid) {
console.log('Submitted:', result.object);
}
};
return (
);
}
// 4. Wrap once at the app root — all forms below share the renderers
function App() {
return (
);
}
```
## How It Works — Step by Step
1. **Define a schema** using `@cleverbrush/schema` — this is your single source of truth for types, validation rules, and field metadata
2. **Register renderers** via `FormSystemProvider` — plain functions that map schema types (`"string"`, `"number"`, `"boolean"`) to your UI components (plain HTML, MUI, Ant Design, etc.)
3. **Create a form instance** via `useSchemaForm(schema)` — returns state management, validation, submit/reset lifecycle
4. **Render fields** via ` t.name} form={form} />` — the component looks up the registered renderer for the field's schema type
5. **Submit** — `form.submit()` runs the schema's full validation and returns a typed result
## Core Concepts
| Part | Responsibility | When to Use |
|------|---------------|-------------|
| **FormSystemProvider** | Global renderer registry via React Context | Once at the app root |
| **useSchemaForm** | Per-schema form instance (state, validation, lifecycle) | In every component that needs a form |
| **useField** | Descriptor-based field binding (value, dirty, touched, error) | When you want fine-grained control |
| **Field** | UI-agnostic component that resolves renderers by schema type | For most form fields — quick and declarative |
## Registering Renderers
Renderers are plain functions that receive field state and return React nodes. Define a renderer map keyed by schema type (`string`, `number`, `boolean`, etc.):
### Plain HTML
```tsx
import { FieldRenderProps } from '@cleverbrush/react-form';
const htmlRenderers = {
string: ({ value, onChange, onBlur, error, touched, label, name, fieldProps }: FieldRenderProps) => (
),
boolean: ({ value, onChange, label }: FieldRenderProps) => (
)
};
```
### Variant Renderers
You can register renderers for specific variants using a `"type:variant"` key.
When `` is rendered on a `string` field, the
registry is checked for `"string:password"` first, then falls back to `"string"`:
```tsx
const renderers = {
// Default string renderer
string: ({ value, onChange, onBlur, error, touched, label, name, fieldProps }: FieldRenderProps) => (
),
// Password variant — rendered when is used on a string field
'string:password': ({ value, onChange, onBlur, error, touched, label, name, fieldProps }: FieldRenderProps) => (