Start here

Install Formedible and render a form.

Install the registry item, add fields, then submit real values. Tune the copied files after the first form works.

Install the component

Run this in the app that owns your UI components. It copies the hook, fields, validation helpers, and types into your project.

Run the command in your web app package.
Import the copied hook from your local UI path.
Commit the copied files so your team can edit them.
The install also drops the Formedible agent skill into `.claude/skills/formedible/` and `.agents/skills/formedible/` so coding agents learn the API. Agents that need it manually: `pnpm dlx skills add DimitriGilbert/Formedible`.

Install formedible-core

bash

pnpm dlx shadcn@latest add https://formedible.dev/r/formedible-core.json

Create a form

Start with fields, default values, and onSubmit. Render the Form component returned by the hook.

Keep field names aligned with your value keys.
Set every default value up front.
Call your real submit function inside onSubmit.

First working form

tsx

import { useFormedible } from '@/components/ui/formedible/hooks/use-formedible';

type ContactValues = {
  name: string;
  email: string;
  message: string;
};

async function saveContact(values: ContactValues): Promise<void> {
  await fetch('/api/contact', {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify(values),
  });
}

export function ContactForm() {
  const contactForm = useFormedible<ContactValues>({
    fields: [
      { name: 'name', type: 'text', label: 'Name' },
      { name: 'email', type: 'email', label: 'Email' },
      { name: 'message', type: 'textarea', label: 'Message' },
    ],
    formOptions: {
      defaultValues: { name: '', email: '', message: '' },
      onSubmit: async ({ value }) => {
        await saveContact(value);
      },
    },
  });

  return <contactForm.Form className="space-y-4" />;
}

Add schema validation

Put the Zod schema on the top-level schema option. Keep field names and schema keys in sync.

Keep schema keys and field names the same.
Use schema at the top level, not formOptions.validators.
Keep built-in required and email checks on the field config when useful.

Top-level schema

tsx

import { z } from 'zod';

import { useFormedible } from '@/components/ui/formedible/hooks/use-formedible';

const contactSchema = z.object({
  name: z.string().min(2, 'Name must be at least 2 characters'),
  email: z.string().email('Enter a valid email'),
  message: z.string().min(10, 'Message must be at least 10 characters'),
});

type ContactValues = z.infer<typeof contactSchema>;

async function saveContact(values: ContactValues): Promise<void> {
  await fetch('/api/contact', {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify(values),
  });
}

export function ContactForm() {
  const contactForm = useFormedible({
    schema: contactSchema,
    fields: [
      { name: 'name', type: 'text', label: 'Full name', required: true },
      { name: 'email', type: 'email', label: 'Email', required: true },
      { name: 'message', type: 'textarea', label: 'Message' },
    ],
    formOptions: {
      defaultValues: { name: '', email: '', message: '' },
      onSubmit: async ({ value }) => {
        await saveContact(value);
      },
    },
  });

  return <contactForm.Form className="space-y-4" />;
}

Customize the copied fields

For one field, pass component. For app-wide defaults, edit the copied field files or use defaultComponents.

Use component for one field override.
Use defaultComponents for a type-wide override.
Edit the copied field registry for a permanent local default.

One field override

tsx

import { useFormedible } from '@/components/ui/formedible/hooks/use-formedible';
import type { FormedibleFieldRenderProps } from '@/components/ui/formedible/lib/types';

function CompactTextField({ fieldConfig, field }: FormedibleFieldRenderProps) {
  const value = typeof field.value === 'string' ? field.value : '';

  return (
    <label className="grid gap-1 text-sm">
      <span className="font-medium">{fieldConfig.label}</span>
      <input
        id={field.id}
        name={field.name}
        value={value}
        placeholder={fieldConfig.placeholder}
        className="h-9 rounded-md border px-3"
        aria-invalid={field.error ? true : undefined}
        onBlur={field.onBlur}
        onChange={(event) => field.onChange(event.target.value)}
      />
      {field.error ? <span className="text-xs text-destructive">{field.error}</span> : null}
    </label>
  );
}

export function ProfileForm() {
  const profileForm = useFormedible({
    fields: [
      { name: 'displayName', type: 'text', label: 'Display name', component: CompactTextField },
    ],
    formOptions: { defaultValues: { displayName: '' } },
  });

  return <profileForm.Form className="space-y-4" />;
}

Where to go next

Use the next page that matches what you are changing. Open a live example when you want a working config to copy.

Fields: choose text, select, arrays, objects, and custom field options.
Validation: add schema, field, async, or cross-field rules.
API: check persistence, analytics, pages, tabs, labels, and wrappers.

Install the registry item

Add the built registry item to your app, then import the copied hook from your local UI package.

pnpm dlx shadcn@latest add https://formedible.dev/r/formedible-core.json

Typed fields over TanStack Form

Formedible renders shadcn-compatible fields while keeping TanStack Form in reach.

import { z } from 'zod';

import { useFormedible } from '@/components/ui/formedible/hooks/use-formedible';

const onboardingSchema = z.object({
  name: z.string().min(2),
  plan: z.enum(['starter', 'team', 'enterprise']),
  needsMigration: z.boolean(),
});

type OnboardingValues = z.infer<typeof onboardingSchema>;

type WorkspaceRecord = OnboardingValues & {
  slug: string;
};

const workspaceRecords: WorkspaceRecord[] = [];

function createWorkspace(values: OnboardingValues): WorkspaceRecord {
  const workspace = {
    ...values,
    slug: values.name.trim().toLowerCase().replace(/\s+/g, '-'),
  };

  workspaceRecords.push(workspace);
  return workspace;
}

export function OnboardingForm() {
  const { Form } = useFormedible<OnboardingValues>({
    fields: [
      { name: 'name', type: 'text', label: 'Workspace name', required: true },
      { name: 'plan', type: 'radio', label: 'Plan', options: ['starter', 'team', 'enterprise'] },
      { name: 'needsMigration', type: 'switch', label: 'Import an existing form system?' },
    ],
    schema: onboardingSchema,
    formOptions: {
      defaultValues: { name: '', plan: 'team', needsMigration: false },
      onSubmit: ({ value }) => {
        createWorkspace(value);
      },
    },
  });

  return <Form />;
}