@cleverbrush/react-form

Quick Start

Define a schema, register renderers, create a form, and render fields — all type-safe. The schema and renderers are defined once per app and reused by every form — individual form components only declare which fields to show:

import { object, string, number } from '@cleverbrush/schema';
import {
  useSchemaForm, Field, FormSystemProvider
} from '@cleverbrush/react-form';

// 1. Define your schema once — 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')
    .maxLength(100, 'Name must be at most 100 characters'),
  email: string()
    .required('Email is required')
    .matches(
      /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
      'Please enter a valid email address'
    ),
  age: number()
    .required('Age is required')
    .min(18, 'Must be at least 18 years old')
    .max(120, 'Must be at most 120')
});

// 2. Register renderers once at the app root — every form inherits them
const renderers = {
  string: ({ value, onChange, onBlur, touched, error }) => (
    <div>
      <input
        type="text"
        value={value ?? ''}
        onChange={(e) => onChange(e.target.value)}
        onBlur={onBlur}
      />
      {touched && error && <span className="error">{error}</span>}
    </div>
  ),
  number: ({ value, onChange, onBlur, touched, error }) => (
    <div>
      <input
        type="number"
        value={value ?? ''}
        onChange={(e) => onChange(Number(e.target.value))}
        onBlur={onBlur}
      />
      {touched && error && <span className="error">{error}</span>}
    </div>
  )
};

// 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 (
    <div>
      <Field forProperty={(t) => t.name} form={form} />
      <Field forProperty={(t) => t.email} form={form} />
      <Field forProperty={(t) => t.age} form={form} />
      <button onClick={handleSubmit}>Submit</button>
    </div>
  );
}

// 4. Wrap once at the app root — all forms below share the renderers
function App() {
  return (
    <FormSystemProvider renderers={renderers}>
      <ContactForm />
    </FormSystemProvider>
  );
}

Try it live

This is the exact form described above, rendered with @cleverbrush/react-form. Try submitting with empty fields, a short name, an invalid email, or an out-of-range age to see validation in action:

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") to your UI components (plain HTML, MUI, Ant Design, etc.)
3. Create a form instance via useSchemaForm(schema) — returns state management, validation, and submit/reset lifecycle
4. Render fields via <Field forProperty={(t) => t.name}form={form}/> — the component looks up the registered renderer for the field's schema type automatically
5. Submit — form.submit() runs the schema's full validation and returns a typed result with per-field errors

Core Concepts

Registering Renderers

Renderers are plain functions that receive field state and return React nodes. They map schema type names (like "string", "number", "boolean") to UI components. Here are two examples:

Plain HTML Renderers

const htmlRenderers = {
  string: ({ value, onChange, onBlur, error, dirty, label, name, fieldProps }) => (
    <div className="field">
      {label && <label>{label}</label>}
      <input
        type="text"
        name={name}
        value={value ?? ''}
        onChange={(e) => onChange(e.target.value)}
        onBlur={onBlur}
        className={error ? 'input-error' : ''}
        {...fieldProps}
      />
      {dirty && <span className="dirty-indicator">*</span>}
      {error && <span className="error">{error}</span>}
    </div>
  ),
  number: ({ value, onChange, onBlur, error, label, name, fieldProps }) => (
    <div className="field">
      {label && <label>{label}</label>}
      <input
        type="number"
        name={name}
        value={value ?? ''}
        onChange={(e) => onChange(Number(e.target.value))}
        onBlur={onBlur}
        {...fieldProps}
      />
      {error && <span className="error">{error}</span>}
    </div>
  ),
  boolean: ({ value, onChange, onBlur, label }) => (
    <div className="field">
      <label>
        <input
          type="checkbox"
          checked={value ?? false}
          onChange={(e) => onChange(e.target.checked)}
          onBlur={onBlur}
        />
        {label}
      </label>
    </div>
  )
};

Material UI Renderers (Example)

// Example — requires @mui/material (not included in this demo)
const muiRenderers = {
  string: ({ value, onChange, onBlur, error }) => (
    <TextField
      value={value ?? ''}
      onChange={(e) => onChange(e.target.value)}
      onBlur={onBlur}
      error={!!error}
      helperText={error}
      fullWidth
    />
  ),
  number: ({ value, onChange, onBlur, error }) => (
    <TextField
      type="number"
      value={value ?? ''}
      onChange={(e) => onChange(Number(e.target.value))}
      onBlur={onBlur}
      error={!!error}
      helperText={error}
      fullWidth
    />
  )
};

// Swap UI libraries by changing the provider — all forms update!
<FormSystemProvider renderers={muiRenderers}>
  {/* All Field components now render Material UI inputs */}
</FormSystemProvider>

Variant Renderers

Register variant-specific renderers with a "type:variant" key. When <Field variant="password" /> is rendered on a string field, the registry is checked for "string:password" first, then falls back to "string":

const renderers = {
  // Default string renderer
  string: ({ value, onChange, onBlur, error, label, name, fieldProps }) => (
    <div>
      {label && <label>{label}</label>}
      <input type="text" name={name} value={value ?? ''}
             onChange={(e) => onChange(e.target.value)} onBlur={onBlur}
             {...fieldProps} />
      {error && <span className="error">{error}</span>}
    </div>
  ),
  // Password variant — used when <Field variant="password" />
  'string:password': ({ value, onChange, onBlur, error, label, name, fieldProps }) => (
    <div>
      {label && <label>{label}</label>}
      <input type="password" name={name} value={value ?? ''}
             onChange={(e) => onChange(e.target.value)} onBlur={onBlur}
             {...fieldProps} />
      {error && <span className="error">{error}</span>}
    </div>
  ),
  // Textarea variant
  'string:textarea': ({ value, onChange, onBlur, error, label, name, fieldProps }) => (
    <div>
      {label && <label>{label}</label>}
      <textarea name={name} value={value ?? ''}
                onChange={(e) => onChange(e.target.value)} onBlur={onBlur}
                {...fieldProps} />
      {error && <span className="error">{error}</span>}
    </div>
  )
};

// Usage:
<Field forProperty={(t) => t.name} form={form} label="Name" />
<Field forProperty={(t) => t.password} form={form}
       variant="password" label="Password"
       fieldProps={{ placeholder: 'Enter password', autoComplete: 'current-password' }} />
<Field forProperty={(t) => t.bio} form={form}
       variant="textarea" label="Bio"
       fieldProps={{ rows: 4 }} />

FormSystemProvider

FormSystemProvider is a React context provider that makes renderers available to all Field components underneath it. Place it once at the root of your app:

import { FormSystemProvider } from '@cleverbrush/react-form';

function App() {
  return (
    <FormSystemProvider renderers={myRenderers}>
      {/* All forms in your app go here */}
    </FormSystemProvider>
  );
}

You can nest providers to override renderers in specific parts of your app. Child providers merge with parent renderers, so you only need to specify the overrides.

useSchemaForm

The main hook for creating form instances. Returns everything you need to manage form state:

const form = useSchemaForm(MySchema, {
  createMissingStructure: true,  // default: true
  validateOnMount: false,        // default: false — set to true to show errors on mount
  validationDebounceMs: 300      // optional — debounce onChange validation (ms)
});

Returned API

useField

Access individual field state and handlers. Can be used via form.useField(forProperty) directly or via the context-based useField(forProperty) inside a FormProvider.

Returned State

Headless Usage

You don't have to use the Field component at all. Use form.useField() directly for full control over rendering:

function MyForm() {
  const form = useSchemaForm(ContactSchema);
  const name = form.useField((t) => t.name);
  const email = form.useField((t) => t.email);

  return (
    <div>
      <label>
        Name
        <input
          value={name.value ?? ''}
          onChange={(e) => name.onChange(e.target.value)}
          onBlur={name.onBlur}
        />
        {name.touched && name.error && (
          <span className="error">{name.error}</span>
        )}
      </label>

      <label>
        Email
        <input
          value={email.value ?? ''}
          onChange={(e) => email.onChange(e.target.value)}
          onBlur={email.onBlur}
        />
        {email.dirty && <span>(modified)</span>}
        {email.error && <span className="error">{email.error}</span>}
      </label>

      <button onClick={() => form.submit()}>Submit</button>
    </div>
  );
}

Field Component

The Fieldcomponent is a declarative way to render form fields. It looks up the registered renderer for the field's schema type and passes the field state to it. Use variant for type-specific rendering, and label, name, fieldProps to forward additional rendering hints:

// Uses the renderer registered for "string" schema type
<Field forProperty={(t) => t.name} form={form} />

// Variant-based resolution: looks up "string:password", falls back to "string"
<Field forProperty={(t) => t.password} form={form} variant="password" />

// With label, name, and extra props for the renderer
<Field
  forProperty={(t) => t.email}
  form={form}
  label="Email address"
  name="email"
  fieldProps={{ placeholder: 'you@example.com', autoComplete: 'email' }}
/>

// Override the renderer for a specific field
<Field
  forProperty={(t) => t.email}
  form={form}
  renderer={({ value, onChange, error }) => (
    <div>
      <input type="email" value={value ?? ''} onChange={(e) => onChange(e.target.value)} />
      {error && <span>{error}</span>}
    </div>
  )}
/>

Props

FormProvider

FormProvider puts a form instance into React context, allowing child components to use the context-based useField hook without passing the form prop explicitly:

import { FormProvider, useField } from '@cleverbrush/react-form';

function NameField() {
  // No need to pass form prop — reads from context
  const name = useField((t) => t.name);
  return (
    <input
      value={name.value ?? ''}
      onChange={(e) => name.onChange(e.target.value)}
      onBlur={name.onBlur}
    />
  );
}

function MyForm() {
  const form = useSchemaForm(ContactSchema);
  return (
    <FormProvider form={form}>
      <NameField />
      {/* other fields */}
    </FormProvider>
  );
}

Nested Objects

PropertyDescriptor selectors support nested paths. Access deeply nested fields with dot notation in the forProperty accessor:

const AddressSchema = object({
  city:   string().minLength(1),
  street: string().minLength(1),
  zip:    string().minLength(5).maxLength(10)
});

const UserSchema = object({
  name:    string().minLength(2),
  address: AddressSchema
});

function UserForm() {
  const form = useSchemaForm(UserSchema);

  return (
    <div>
      <Field forProperty={(t) => t.name} form={form} />
      <Field forProperty={(t) => t.address.city} form={form} />
      <Field forProperty={(t) => t.address.street} form={form} />
      <Field forProperty={(t) => t.address.zip} form={form} />
    </div>
  );
}

Validation

Validation is built into the schema — you don't configure it separately. Here's how it works step by step:

1. Schema constraints (minLength, max, matches, etc.) are checked first
2. Custom validators added via .addValidator() run next (can be async)
3. Per-field errors are extracted and made available via useField().error
4. form.submit() triggers full validation and returns the result

Custom Validator Example

const RegistrationSchema = object({
  username: string().minLength(3).maxLength(20).addValidator(async (value) => {
    // Check if username is taken (async!)
    const taken = await checkUsernameAvailability(value);
    if (taken) {
      return { valid: false, errors: [{ message: 'This username is already taken' }] };
    }
    return { valid: true };
  }),
  password: string().minLength(8, 'Password must be at least 8 characters'),
  confirmPassword: string().minLength(8, 'Please confirm your password')
}).addValidator(async (value) => {
  // Object-level validation
  if (value.password !== value.confirmPassword) {
    return { valid: false, errors: [{ message: 'Passwords do not match' }] };
  }
  return { valid: true };
});

Comparison with Alternatives

API Reference

Hooks

Components

Types