Fillout Flow

Installation

pnpm dlx shadcn@latest add @blocks/fillout-flow

New to Circle? Get started.

About

Use this when Fillout is your source of truth for questions, but you want the actual product journey to run in Circle UI instead of the native Fillout embed.

Usage

import {
  FilloutFlow,
  createFilloutFlowDefinition,
  type FilloutFormMetadata,
} from "@circle/ui";

const flow = createFilloutFlowDefinition(form as FilloutFormMetadata, {
  submitLabel: "Send",
  steps: [
    { id: "goal", fields: ["kaRM"] },
    { id: "details", title: "Tell us about you", fields: ["h8ay", "goHS", "nugy"] },
  ],
});

<FilloutFlow
  flow={flow}
  urlParameters={{ patient_id: patientId }}
  onSubmit={(payload) =>
    fetch("/api/fillout/submissions", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(payload),
    })
  }
/>;

When to use

This block is happiest with the common input types we already map: single and multi choice, text, long text, email, phone, number, and date. For rarer Fillout field types, add a kind override or a custom field renderer.

Typical flow setup

1. Fetch Fillout form metadata on the server or through your own safe API route.
2. Create a flow definition by grouping Fillout question ids into step specs.
3. Render `FilloutFlow` and hand the submit callback a route that posts the resulting payload back to Fillout.

Works with

• flowUse the lower-level flow primitives directly when you want to build the journey shell yourself.
• use-fillout-flowUse the hook alone when you want the schema and submission logic but fully custom rendering.
• fillout-flow-schemaUse the pure schema helpers to map Fillout form metadata into your own flow model.
• fillout-flow-submissionUse the payload helpers directly when answers are collected somewhere else.

Dependencies