Skip to main content

Quick Start

Get a working form rendering in under 5 minutes.

1. Install​

npm install @fogpipe/forma-core @fogpipe/forma-react

2. Render a Form​

Forma React ships with default components — pre-built, styled, accessible field components that cover all 18 field types. Import them and render:

ContactPage.tsx
import { DefaultFormRenderer } from "@fogpipe/forma-react/defaults";
import "@fogpipe/forma-react/defaults/styles.css";
import type { Forma } from "@fogpipe/forma-core";

const contactForm: Forma = {
  version: "1.0",
  meta: { id: "contact-form", title: "Contact Us" },
  schema: {
    type: "object",
    properties: {
      name: { type: "string" },
      email: { type: "string", format: "email" },
      subscribe: { type: "boolean" },
    },
    required: ["name", "email"],
  },
  fields: {
    name: { type: "text", label: "Your Name", placeholder: "Enter your name" },
    email: {
      type: "email",
      label: "Email Address",
      placeholder: "you@example.com",
    },
    subscribe: { type: "boolean", label: "Subscribe to newsletter" },
  },
  fieldOrder: ["name", "email", "subscribe"],
};

function ContactPage() {
  return (
    <DefaultFormRenderer
      spec={contactForm}
      onSubmit={(data) => console.log("Submitted:", data)}
    />
  );
}

That's it. You get a styled form with validation, error display, and a submit button.

3. Customize the Theme​

Override CSS variables to match your brand — no component code needed:

theme.css
:root {
  --forma-color-primary: #7c3aed;
  --forma-radius: 12px;
  --forma-font-family: "Inter", sans-serif;
}

See Default Components — Theming for the full variable reference.

4. Add Wizard Navigation​

For multi-page forms, add wizardLayout:

<DefaultFormRenderer
  spec={multiPageSpec}
  onSubmit={handleSubmit}
  wizardLayout
/>

How It Works​

Forma React is headless — it separates form logic from UI. Under the hood:

  1. Forma spec defines the form structure, validation rules, and conditional logic
  2. useForma hook manages all state — values, errors, visibility, computed fields, wizard navigation
  3. Components render the UI for each field type
  4. FormRenderer wires everything together

The default components are one implementation of step 3. When you need full control over your UI — custom design systems, Tailwind, Radix, shadcn — you can replace any or all components:

import { FormRenderer } from "@fogpipe/forma-react";
import { defaultComponentMap } from "@fogpipe/forma-react/defaults";

// Replace just select, keep defaults for everything else
const components = { ...defaultComponentMap, select: MyFancySelect };

<FormRenderer spec={spec} components={components} onSubmit={handleSubmit} />;

Or build an entirely custom component map from scratch — see Component Mapping.

Next Steps​