Forms Module Recipe

The Forms module is a ready-made /forms experience — a visual form builder plus a runtime renderer on top of the schema-driven CollectionForm. An admin arranges a collection’s fields into ordered sections, sets width / required / readonly / hidden, and authors conditional logic, then saves the result as a reusable, named form definition. Definitions are stored as items in an ordinary collection and merged onto the live schema at render time via buildFieldsFromDefinition — the schema is never mutated.

It gives you four routes:

• /forms — the list of saved forms, each linking to the builder (edit) and the fill-out page.
• /forms/new — create a form: Start from scratch (auto-create a new fb_-prefixed collection on save) or Use an existing collection (bind to one you already have).
• /forms/[id] — the visual FormBuilder editor (palette / canvas / settings, with a live Preview tab).
• /forms/[id]/fill — renders the form with DynamicForm to create a real item in the target collection.

The pieces

Prerequisite: the definitions collection

Form definitions are persisted as items in a single collection (default fb_definitions). It is an ordinary user collection — not a daas_-prefixed system collection — and must exist before the builder can save:

If the collection is missing, the list and builder render a FormsEmptyState hint describing exactly this instead of failing. With DaaS schema rights that hint also offers a one-click Create collection action, so you never have to leave the app.

Install

buildpad add form-builder forms-routes

buildpad add api-routes

The routes

Four files give you the whole module. They live under the (authenticated) route group, so they render inside the App Shell:

app/[lang]/(authenticated)/forms/
├── page.tsx            # /forms          — list of saved definitions
├── new/page.tsx        # /forms/new      — create (auto-create or bind existing)
├── [id]/page.tsx       # /forms/[id]     — the FormBuilder editor
└── [id]/fill/page.tsx  # /forms/[id]/fill — render with DynamicForm to create an item

The examples below are trimmed to the wiring. The generated pages also add breadcrumbs, loading states, and translated strings (app.forms.*).

"use client";
 
import React, { useEffect, useState } from 'react';
import { useLocaleRouter } from '@/lib/i18n/navigation';
import { useI18n } from '@/lib/i18n/provider';
import { FormsEmptyState, type FormDefinition } from '@/components/ui/form-builder';
import { useFormDefinitions } from '@/lib/buildpad/hooks';
 
export default function FormsListPage() {
  const router = useLocaleRouter();
  const { t } = useI18n();
  const { list } = useFormDefinitions();
  const [definitions, setDefinitions] = useState<FormDefinition[]>([]);
  const [error, setError] = useState<string | null>(null);
 
  useEffect(() => {
    list()
      .then(setDefinitions)
      .catch((err: unknown) => setError(err instanceof Error ? err.message : t('app.forms.loadFailed')));
  }, []);
 
  if (error) return <FormsEmptyState error={error} />;
  // …a "New form" button (router.push('/forms/new')) and one row per definition,
  // linking to `/forms/${def.id}` and `/forms/${def.id}/fill`
}

import { FormBuilder } from '@/components/ui/form-builder';
import { useLocaleRouter } from '@/lib/i18n/navigation';
 
// inside the page component:
const router = useLocaleRouter();
 
// auto-create on save (needs schema rights):
<FormBuilder onSaved={(def) => router.push(`/forms/${def.id}`)} />
 
// bind to an existing collection (hybrid storage):
<FormBuilder targetCollection="issues" onSaved={(def) => router.push(`/forms/${def.id}`)} />

"use client";
 
import React, { use } from 'react';
import { FormBuilder } from '@/components/ui/form-builder';
 
export default function EditFormPage({ params }: { params: Promise<{ id: string }> }) {
  const { id } = use(params);
  // …breadcrumbs and a "Fill out" button (router.push(`/forms/${id}/fill`))
  return <FormBuilder definitionId={id} />;
}

"use client";
 
import React, { use } from 'react';
import { useLocaleRouter } from '@/lib/i18n/navigation';
import { DynamicForm } from '@/components/ui/form-builder';
 
export default function FillFormPage({ params }: { params: Promise<{ id: string }> }) {
  const { id } = use(params);
  const router = useLocaleRouter();
  return (
    <DynamicForm
      definitionId={id}
      onSuccess={() => router.push('/forms')}
      onCancel={() => router.push('/forms')}
    />
  );
}

Conditions

ConditionsEditor authors the exact FieldCondition[] shape the runtime already consumes (apply-conditions.ts), so conditions evaluate without translation. Rules are built with FilterPanel, producing DaaS-compatible filter JSON (_eq, _neq, _in, _and, _or, …). When multiple conditions match, the last one wins (DaaS convention).

Data storage & searchability

The form definition (the overlay JSON) is config; the form data (the answers users submit) is what you later search and report on. This module stores answers as real, typed DaaS columns by default — natively searchable, sortable, aggregatable, relatable, and field-level-permissioned through the Items API — with a single opt-in extras jsonb column as the escape hatch for the rare non-searchable tail.

Two strategies, derived from the target collection’s schema:

The builder derives the strategy (a collection is full iff it has no extras column) — nothing extra is persisted on the definition. Every field carries store: 'column' | 'extras' (default 'column'); the Add field flow lets you choose, and tick Index this column for fields you’ll filter or sort on.

Because real-column answers are ordinary DaaS columns, the existing Items API is the search layer — ItemsService.readByQuery(...) already speaks filter (20+ operators incl. relational dot-notation), sort, search, aggregate, and groupBy. Model a Project → Issue hierarchy with real relations (an M2O parent + a type discriminator) and a per-type form (definition key), and query across it natively (e.g. filter[project][_eq]=…&filter[issue_type][_eq]=bug).

Multi-tenancy / scopes

• Data requests reuse the existing DaaSProvider header injection, so scoped reads/writes partition by X-Resource-Uri automatically on the direct deployment.
• For a scope-enabled target collection, DynamicForm passes the active scope URI as a create-time default unless DaaS permission presets already inject it.
• Definitions follow a global-baseline + optional per-tenant-override model: by default fb_definitions is unscoped (one form for all tenants); scope-enable it and resolveScreen picks the nearest-ancestor-or-self definition per scope.

Prerequisites

• The module must live under your authenticated layout so DaaSProvider is above it — buildpad init generates this as app/[lang]/(authenticated)/ with a DaaSProviderWrapper. The hooks call your /api/items/* (and, when provisioning in proxy mode, /api/fields/* and /api/collections/*) proxy routes.
• No extra styling is needed: the components consume the design tokens through the Mantine theme. See the Styleguide for the token reference.

See the components live

Every state of the builder and renderer is in the Forms Storybook — FormBuilder, DynamicForm, FormPreview, ConditionsEditor, and the supporting pieces. Run it locally with pnpm --filter @buildpad/ui-forms storybook (port 6010). The Live DaaS stories of FormBuilder and DynamicForm connect to a real DaaS instance through the storybook-host proxy.