@rilaykit/forms

@rilaykit/forms

The form builder and React rendering layer for RilayKit — build type-safe, headless forms from declarative schemas.

@rilaykit/forms provides a fluent builder API to define form configurations and headless React components to render them. State management is powered by Zustand with granular selectors for optimal re-render performance.

Installation

# pnpm (recommended)
pnpm add @rilaykit/core @rilaykit/forms

# npm
npm install @rilaykit/core @rilaykit/forms

# yarn
yarn add @rilaykit/core @rilaykit/forms

# bun
bun add @rilaykit/core @rilaykit/forms

@rilaykit/core is a required peer dependency.

Requirements

• React >= 18
• React DOM >= 18

Quick Start

1. Create Your Registry

import { ril } from '@rilaykit/core';
import { Input } from './components/Input';

const rilay = ril.create()
  .addComponent('input', { renderer: Input });

2. Build a Form

import { form } from '@rilaykit/forms';
import { required, email } from '@rilaykit/core';

const loginForm = form
  .create(rilay, 'login')
  .add({
    id: 'email',
    type: 'input',
    props: { label: 'Email', type: 'email' },
    validation: { validate: [required(), email()] },
  })
  .add({
    id: 'password',
    type: 'input',
    props: { label: 'Password', type: 'password' },
    validation: { validate: [required()] },
  });

3. Render It

import { Form, FormField } from '@rilaykit/forms';

function LoginForm() {
  const handleSubmit = (data: { email: string; password: string }) => {
    console.log('Login:', data);
  };

  return (
    <Form formConfig={loginForm} onSubmit={handleSubmit}>
      <FormField fieldId="email" />
      <FormField fieldId="password" />
      <button type="submit">Sign In</button>
    </Form>
  );
}

Features

Fluent Form Builder

Construct forms with a chainable, type-safe API. Each field type and its props are validated at compile time.

import { form } from '@rilaykit/forms';

const contactForm = form
  .create(rilay, 'contact')
  .add(
    { id: 'firstName', type: 'input', props: { label: 'First Name' } },
    { id: 'lastName', type: 'input', props: { label: 'Last Name' } },
  )
  .add({
    id: 'message',
    type: 'textarea',
    props: { label: 'Message', rows: 5 },
    validation: { validate: [required()] },
  });

// Serialize, clone, inspect
const json = contactForm.toJSON();
const variant = contactForm.clone('contact-v2');
const stats = contactForm.getStats();

Headless React Components

Zero HTML, zero CSS. You provide the renderers, RilayKit handles state, validation, and orchestration.

Component	Description
<Form>	Main wrapper — manages context, state, and submission
<FormProvider>	Context provider (used separately from Form when needed)
<FormBody>	Renders the full form body from configuration
<FormField>	Renders a single field by ID
<FormRow>	Renders a row of fields
<FormSubmitButton>	Submit button with loading/disabled state

Zustand-Powered Store

Each form instance gets its own Zustand store with granular selectors — only the fields that change trigger re-renders.

import {
  useFieldValue,
  useFieldErrors,
  useFieldTouched,
  useFieldState,
  useFormValues,
  useFormValid,
  useFormDirty,
  useFormSubmitting,
  useFieldActions,
  useFormActions,
} from '@rilaykit/forms';

function CustomField({ fieldId }: { fieldId: string }) {
  const value = useFieldValue(fieldId);
  const errors = useFieldErrors(fieldId);
  const { setValue, setTouched } = useFieldActions(fieldId);
  // ...
}

Conditional Fields

Combined with @rilaykit/core's condition system, fields show/hide reactively based on other field values.

import { when } from '@rilaykit/core';

form.create(rilay, 'account')
  .add({
    id: 'accountType',
    type: 'select',
    props: { options: [{ value: 'business', label: 'Business' }] },
  })
  .add({
    id: 'companyName',
    type: 'input',
    props: { label: 'Company Name' },
    conditions: { visible: when('accountType').equals('business') },
  });

Validation

Supports built-in validators, Standard Schema libraries (Zod, Valibot, Yup...), and custom validators — all in the same field.

import { z } from 'zod';
import { required } from '@rilaykit/core';

validation: {
  validate: [required(), z.string().email()],
  validateOnBlur: true,
}

API Overview

Builder

Method	Description
form.create(ril, id?)	Create a new form builder
.add(...fields)	Add fields to the form
.addSeparateRows(fields)	Each field on its own row
.updateField(id, updates)	Update a field definition
.removeField(id)	Remove a field
.setValidation(config)	Set form-level validation
.addFieldConditions(id, conditions)	Add conditional logic
.build()	Produce the final FormConfiguration
.toJSON() / .fromJSON(json)	Serialize / deserialize
.clone(newId?)	Clone the form configuration

Hooks

Hook	Description
useFieldValue(id)	Current field value
useFieldErrors(id)	Field validation errors
useFieldTouched(id)	Whether field has been touched
useFieldState(id)	Combined field state
useFieldActions(id)	setValue, setTouched, etc.
useFieldConditions(id)	Evaluated condition results
useFormValues()	All form values
useFormValid()	Whether form is valid
useFormDirty()	Whether form has unsaved changes
useFormSubmitting()	Whether form is submitting
useFormActions()	submit, reset, validate, etc.

Architecture

@rilaykit/core          (registry, types, validation, conditions)
    ↑
@rilaykit/forms         ← you are here
    ↑
@rilaykit/workflow      (multi-step workflows)

Server-Driven Forms

Generate forms from JSON schemas sent by the backend — no frontend redeployment needed.

import { fromSchema } from '@rilaykit/forms';

const { formConfig, defaultValues } = fromSchema(schema, rilConfig, registry);

Supports validation descriptors, conditions, effects via registry handlers, and repeatable groups. See the Server-Driven Forms guide for details.

Documentation

Full documentation at rilay.dev:

• Building Forms
• Rendering Forms
• Form Validation
• Advanced Forms
• Server-Driven Forms
• Form Hooks
• API Reference

License

MIT — see LICENSE for details.