react-formbridge

Describe forms once. Ship them everywhere

@runilib/react-formbridge

Schema-first form layer for
React and
React Native.

A headless architecture to manage form state, complex validation, and conditional logic with a single source of truth for web and mobile.

Get StartedView on GitHub
import type { FormSchema } from '@runilib/react-formbridge'
import { field, useFormBridge } from '@runilib/react-formbridge'

const schema = {
  email: field.email('Work email').required().trim().lowercase(),
  password: field.password('Password').required().strong(),
  role: field.select('Role').options(['admin', 'editor', 'viewer']).required(),
  terms: field.checkbox('Accept terms').mustBeTrue(),
} satisfies FormSchema

export function SignupForm() {
  const { Form, fields, state } = useFormBridge(schema, {
    validateOn: 'onTouched',
    persist: { key: 'signup-form-web' },
  })

  return (
    <Form
      onSubmit={async (values) => {
        console.log('Submitted values', values)
        if (typeof window !== 'undefined') {
          window.alert(JSON.stringify(values, null, 2))
        }
      }}
    >
      <fields.email />
      <fields.password />
      <fields.role />
      <fields.terms />
      <Form.Submit disabled={!state.isValid}>Create account</Form.Submit>
    </Form>
  )
}

export default SignupForm
Open on CodeSandboxOpen Sandbox
WebSame schema-first API, with a web form or a native screen around it.

Core Principles

Schema-driven rendering

Map your schema directly to UI components so each field stays typed, validated, and consistent.

Platform-specific UI

Pass specialized props to web or native components through a single unified schema entry.

Batteries-included validation

Built-in fluent validation covers every common rule. No need to install Zod, Yup, or any external library.

Provider-free usage

No provider is required for the default flow. Start from a schema and ship the form runtime directly.

What you get

One schema for web and native

Keep the form definition as the source of truth and reuse the same runtime shape across React and React Native.

Typed generated fields

useFormBridge() returns a ready-to-render Form wrapper and field components with UI props scoped to each platform.

Validation included

Every field carries its own fluent validation rules. No external library required - everything ships with the package.

Production patterns included

Draft persistence, async options, readonly views, dynamic forms, analytics hooks, and wizards are documented end to end.

Headless Logic Architecture

FormBridge decouples the data model from the UI rendering layer. Write your validation and business logic once, implement the visual layer twice.

  • Total PortabilityMove from Web to React Native without rewriting a single rule.
  • Deterministic StateForm state management behaves identically across environments.
WEB UI
FORM ENGINE
NATIVE UI

Get started in 3 steps

1

Install

npm install @runilib/react-formbridge
2

Define your schema

Describe every field, its type, validation rules, and default value in a single TypeScript object.

3

Render on any platform

Call useFormBridge(schema) and get a typed Form wrapper plus ready-to-render field components for web or native.

Primitive Field Builders

Base field buildertextemailpasswordtelurltextareanumbercheckboxswitchselectradiodatephonemaskedfileotpcustominferinferType

Engineered for...

Dynamic Form FlowsShow, hide, or rearrange fields based on user input with reactive conditional logic.
Complex Nested ObjectsModel deeply nested data structures and keep validation scoped to each level.
Dynamic Field ArraysLet users add or remove repeatable groups while the schema stays consistent.
High-perf Async LogicDebounced remote validation, async select options, and optimistic state updates.

Built for real-world flows

Signup and account creation

Start from a small schema, add password strength, cross-field validation, and draft recovery without hand-wiring input state.

Checkout and billing

Use masked fields, phone inputs, dynamic country-specific requirements, and saved progress for longer purchase flows.

Back-office and CRUD editing

Seed existing values, infer fields from data structures, and pair edit forms with readonly or diff views for approval steps.

Multi-step onboarding

Split large schemas into wizard steps, keep validation predictable, and preserve a shared submission model across pages or screens.

Popular Documentation Paths

Quick start

Bootstrap your first schema-driven form in minutes.

Draft persistence

Automatically save and restore form progress across sessions.

useFormBridge()

Use the core hook for timing, state, and validation lifecycle.

useFormBridgeWizard()

Orchestrate multi-step flows with branching logic.

field.select()

Configure remote dropdowns with async option loading.

Schema validator bridge (zod, yup, joi, valibot)

Optional bridge for teams already using Zod, Yup, Joi, or Valibot.

Ready to implement schema-driven forms?

Stop duplicating validation logic. Build robust, type-safe forms that scale with your engineering team.

Open documentationView source on GitHub

Does react-formbridge support both React web and React Native?

Yes. The library is designed around one schema-first API that renders on React web and React Native with platform-specific UI surfaces where needed.

Do I need to install Zod, Yup, or any validation library?

No. FormBridge ships with a complete fluent validation API built into every field builder. External adapters exist for teams that already rely on Zod or Yup, but they are entirely optional.

Is react-formbridge only for simple forms?

No. The docs include async options, conditional fields, persistence, multi-step wizards, inferred schemas, readonly rendering, and analytics hooks for production flows.

Do I need a provider or a custom registry before I can use it?

No. The standard flow is provider-free. You define a schema, call useFormBridge(), and render the generated Form and field components directly.