Inputs

Form

Schema-driven form with built-in validation, sections, and a headless core.

A complete form from a fields config — text, number, textarea, select, checkbox, radio, and switch controls, built-in validation, titled sections, a responsive grid, an error summary, and submit states. Built on a headless external-store core, so typing in one field only re-renders that field; an optional resolver lets you swap the built-in rules for zod / yup later without touching the field config. RSC-safe and dependency-free.

Installation

Add the package. Form ships its own CSS and pulls in the controls it renders — there's no separate stylesheet, no form library, and no validation dependency to wire up.

pnpm add @roy-ui/ui

Import

import { Form } from '@roy-ui/ui';

// or import just this component (its own 'use client' island):
import { Form } from '@roy-ui/ui/form';

Usage

You describe the form as a fields array; Form renders the controls, validates them, lays them out in a responsive grid, and handles submission. Each field's type picks the control — text, number, textarea, select, checkbox, radio, switch. The previews run dark to read against this page; the form is theme-aware either way.

Schema-driven registration

One fields array with two titled sections and a two-column grid (it collapses to one column on mobile). Validation runs once a field is touched; the submit button shows a spinner while onSubmit resolves, then the success line appears. Submit it empty to see the error summary and focus jump to the first invalid field.

tsx

import { Form } from '@roy-ui/ui';
import type { FormField, FormSection } from '@roy-ui/ui';

const fields: FormField[] = [
  { name: 'email', type: 'email', label: 'Work email', section: 'account',
    width: 'half', rules: { required: true, email: true } },
  { name: 'password', type: 'password', label: 'Password', section: 'account',
    width: 'half', rules: { required: true, minLength: 8 } },
  { name: 'tos', type: 'checkbox', label: 'I agree to the terms', section: 'account',
    rules: { required: 'You must accept the terms.' } },
  { name: 'role', type: 'select', label: 'Role', section: 'workspace', width: 'half',
    options: [{ label: 'Engineer', value: 'eng' }, { label: 'Designer', value: 'design' }],
    rules: { required: true } },
  { name: 'seats', type: 'number', label: 'Seats', section: 'workspace', width: 'half',
    min: 1, rules: { required: true, min: 1 } },
  { name: 'plan', type: 'radio', label: 'Plan', section: 'workspace', orientation: 'horizontal',
    options: [{ label: 'Starter', value: 'starter' }, { label: 'Growth', value: 'growth' }],
    rules: { required: true } },
  { name: 'bio', type: 'textarea', label: 'About your team', section: 'workspace',
    autoGrow: true, maxLength: 160, showCount: true },
  { name: 'notifications', type: 'switch', label: 'Email me product updates', section: 'workspace' },
];

const sections: FormSection[] = [
  { id: 'account', title: 'Account', description: 'How you sign in.' },
  { id: 'workspace', title: 'Workspace', description: 'Set up your team.' },
];

<Form
  columns={2}
  fields={fields}
  sections={sections}
  submitLabel="Create account"
  successMessage="Account created — check your inbox."
  onSubmit={async (values) => { await api.register(values); }}
/>

The minimum

No sections, no grid — three fields and a submit. validateMode defaults to onTouched, so a field validates after you leave it and then re-checks as you type.

tsx

const fields = [
  { name: 'email', type: 'email', label: 'Email', rules: { required: true, email: true } },
  { name: 'password', type: 'password', label: 'Password', rules: { required: true } },
  { name: 'remember', type: 'checkbox', label: 'Keep me signed in' },
];

<Form fields={fields} submitLabel="Sign in" onSubmit={signIn} />

Validate on submit

Set validateMode="onSubmit" to hold all errors until the form is submitted. A blocked submit marks every field touched, renders the error summary, and moves focus to the first invalid field — each summary line jumps to its field.

tsx

<Form
  fields={fields}
  validateMode="onSubmit"
  submitLabel="Submit"
  onSubmit={save}
/>

Validation

Each field carries a rules object: required, min / max, minLength / maxLength, pattern, email, url, and a custom validate function with access to every value (for cross-field checks). The built-in engine is the default; pass a resolver to swap it for an external schema later — same path → message contract, so field config never changes.

Rules + cross-field validate

const fields = [
  { name: 'password', type: 'password', label: 'Password',
    rules: { required: true, minLength: 8 } },
  { name: 'confirm', type: 'password', label: 'Confirm password',
    rules: {
      required: true,
      validate: (value, values) =>
        value === values.password ? null : 'Passwords must match',
    } },
];

Swap the engine later (the resolver seam)

// Built-in today — drop in a schema validator tomorrow with no field changes:
// import { zodResolver } from 'your-adapter';
// <Form fields={fields} resolver={zodResolver(schema)} onSubmit={save} />

// A resolver is just: (values, ctx) => Record<fieldName, message>
const upperEmail: FormResolver = (values) =>
  /[A-Z]/.test(String(values.email)) ? { email: 'Use lowercase' } : {};

<Form fields={fields} resolver={upperEmail} onSubmit={save} />

How it renders

Form is a thin schema layer over a headless core: an external store plus per-field subscriptions. Typing in one field updates the store and only that field re-renders — the rest of the form, including sibling fields, stays put. That keeps large forms responsive without a state library. Server errors map back by field name through the submit helpers.

Server-side errors

<Form
  fields={fields}
  onSubmit={async (values, helpers) => {
    const res = await api.register(values);
    if (res.error) {
      // Map server validation back onto fields by name:
      helpers.setErrors({ email: 'That email is already registered' });
    }
  }}
/>

Props

fields and onSubmit are required. Everything else is optional. The field config types (FormField, FieldRules, FormSection, FormResolver) are exported for typed schemas.

Prop	Type	Default	Description
`fields`	`FormField[]`	`—`	Required. The field config — name, type, label, width, section, rules, and per-type options.
`onSubmit`	`(values, helpers) => void \| Promise`	`—`	Required. Called with clean values once validation passes. helpers carry setErrors / setError / reset / setSubmitState.
`sections`	`FormSection[]`	`—`	Titled groups; fields opt in via field.section. Fields with no section render first.
`defaultValues`	`Record<string, unknown>`	`—`	Seed values; wins over each field’s defaultValue.
`values`	`Record<string, unknown>`	`—`	Controlled mode: parent owns the values; pair with onChange.
`onChange`	`(values, { name }) => void`	`—`	Fires on every field change with the full values object.
`resolver`	`FormResolver`	`built-in`	Swap the validation engine. (values, ctx) => Record<name, message>, sync or async.
`validateMode`	`'onChange' \| 'onBlur' \| 'onSubmit' \| 'onTouched'`	`'onTouched'`	When validation first runs for a field.
`reValidateMode`	`'onChange' \| 'onBlur'`	`'onChange'`	When a field re-checks after its first error.
`onInvalid`	`(errors) => void`	`—`	Called with the error map when a submit is blocked.
`submitLabel`	`ReactNode`	`'Submit'`	Submit button label.
`successMessage`	`ReactNode`	`—`	Shown after a successful submit.
`errorMessage`	`ReactNode`	`—`	Shown if onSubmit throws.
`columns`	`1 \| 2 \| 3`	`1`	Base grid columns (sets the default field width). Collapses to one column on mobile.
`theme`	`'light' \| 'dark' \| 'auto'`	`'auto'`	Follow the system (default) or force the built-in light / dark tokens.
`className`	`string`	`—`	Extra classes on the <form>. ref forwards to the form element.

Form

Schema-driven form with built-in validation, sections, and a headless core.

Usage

import { Form } from '@roy-ui/ui'; import type { FormField, FormSection } from '@roy-ui/ui'; const fields: FormField[] = [ { name: 'email', type: 'email', label: 'Work email', section: 'account', width: 'half', rules: { required: true, email: true } }, { name: 'password', type: 'password', label: 'Password', section: 'account', width: 'half', rules: { required: true, minLength: 8 } }, { name: 'tos', type: 'checkbox', label: 'I agree to the terms', section: 'account', rules: { required: 'You must accept the terms.' } }, { name: 'role', type: 'select', label: 'Role', section: 'workspace', width: 'half', options: [{ label: 'Engineer', value: 'eng' }, { label: 'Designer', value: 'design' }], rules: { required: true } }, { name: 'seats', type: 'number', label: 'Seats', section: 'workspace', width: 'half', min: 1, rules: { required: true, min: 1 } }, { name: 'plan', type: 'radio', label: 'Plan', section: 'workspace', orientation: 'horizontal', options: [{ label: 'Starter', value: 'starter' }, { label: 'Growth', value: 'growth' }], rules: { required: true } }, { name: 'bio', type: 'textarea', label: 'About your team', section: 'workspace', autoGrow: true, maxLength: 160, showCount: true }, { name: 'notifications', type: 'switch', label: 'Email me product updates', section: 'workspace' }, ]; const sections: FormSection[] = [ { id: 'account', title: 'Account', description: 'How you sign in.' }, { id: 'workspace', title: 'Workspace', description: 'Set up your team.' }, ]; <Form columns={2} fields={fields} sections={sections} submitLabel="Create account" successMessage="Account created — check your inbox." onSubmit={async (values) => { await api.register(values); }} />

const fields = [ { name: 'email', type: 'email', label: 'Email', rules: { required: true, email: true } }, { name: 'password', type: 'password', label: 'Password', rules: { required: true } }, { name: 'remember', type: 'checkbox', label: 'Keep me signed in' }, ]; <Form fields={fields} submitLabel="Sign in" onSubmit={signIn} />

Validation

const fields = [ { name: 'password', type: 'password', label: 'Password', rules: { required: true, minLength: 8 } }, { name: 'confirm', type: 'password', label: 'Confirm password', rules: { required: true, validate: (value, values) => value === values.password ? null : 'Passwords must match', } }, ];

// Built-in today — drop in a schema validator tomorrow with no field changes: // import { zodResolver } from 'your-adapter'; // <Form fields={fields} resolver={zodResolver(schema)} onSubmit={save} /> // A resolver is just: (values, ctx) => Record<fieldName, message> const upperEmail: FormResolver = (values) => /[A-Z]/.test(String(values.email)) ? { email: 'Use lowercase' } : {}; <Form fields={fields} resolver={upperEmail} onSubmit={save} />

How it renders

<Form fields={fields} onSubmit={async (values, helpers) => { const res = await api.register(values); if (res.error) { // Map server validation back onto fields by name: helpers.setErrors({ email: 'That email is already registered' }); } }} />

Prop

Type

Default

Description

fields

FormField[]

—

Required. The field config — name, type, label, width, section, rules, and per-type options.

onSubmit

(values, helpers) => void | Promise

—

Required. Called with clean values once validation passes. helpers carry setErrors / setError / reset / setSubmitState.

sections

FormSection[]

—

Titled groups; fields opt in via field.section. Fields with no section render first.

defaultValues

Record<string, unknown>

—

Seed values; wins over each field’s defaultValue.

values

Record<string, unknown>

—

Controlled mode: parent owns the values; pair with onChange.

onChange

(values, { name }) => void

—

Fires on every field change with the full values object.

resolver

FormResolver

built-in

Swap the validation engine. (values, ctx) => Record<name, message>, sync or async.

validateMode

'onChange' | 'onBlur' | 'onSubmit' | 'onTouched'

'onTouched'

When validation first runs for a field.

reValidateMode

'onChange' | 'onBlur'

'onChange'

When a field re-checks after its first error.

onInvalid

(errors) => void

—

Called with the error map when a submit is blocked.

submitLabel

ReactNode

'Submit'

Submit button label.

successMessage

ReactNode

—

Shown after a successful submit.

errorMessage

ReactNode

—

Shown if onSubmit throws.

columns

1 | 2 | 3

1

Base grid columns (sets the default field width). Collapses to one column on mobile.

theme

'light' | 'dark' | 'auto'

'auto'

Follow the system (default) or force the built-in light / dark tokens.

className

string

—

Extra classes on the <form>. ref forwards to the form element.