_____ _ _ _ _
| ___| | | | (_) |
| |_ | | _____ __| | ___| |_
| _| | |/ _ \ \ /\ / /| |/ / | __|
| | | | (_) \ V V / | <| | |_
\_| |_|\___/ \_/\_/ |_|\_\_|\__|
( ● )──▶( ● )──▶( ● )──▶( ✓ ) guided flows, from config to done
Flowkit
Source-available library for composing guided, mobile-first, themeable flows from a
declarative config validated with zod. Built for "one question per
screen" wizards such as reports, surveys, onboarding and multi-step forms: you write a
Flow object, Flowkit renders it, handles navigation and validation, and applies the
theme. Licensed under the PolyForm Shield License 1.0.0 from v1.0.0
(v0.x remains MIT).
Multi-framework status: the core (@flowkit-io/core), themes (@flowkit-io/themes) and
adapters (@flowkit-io/adapters) are framework-agnostic by design. The React renderer
(@flowkit-io/react) is complete and covered by automated tests (unit + Playwright
end-to-end). Vue, Svelte and vanilla JS renderers are planned but not yet
implemented in this version.
npm monorepo (workspaces) made up of:
packages/core # Flow/Step schema (zod), open step registry, state machine, oauth, geocoding, i18n
packages/react # <FlowRunner>, <ThemeProvider>, components for every step type (incl. oauth, real map)
packages/themes # warm-paper, mint-fresh, midnight-ink, sunset-clay, rose-quartz, scarlet-ink, showcase themes (tokens + CSS vars, light/dark, custom fonts/images)
packages/adapters # answer persistence: local, rest, notion, receipt-email, supabase (stub)
packages/presets # ready-to-use flows: "odori", "feedback", "restaurant", "anagrafica"
packages/create-flowkit # CLI: `create-flowkit` (scaffold) and `flowkit-init` (installer)
apps/playground # Vite showcase app: preset/theme/dark-mode picker, mobile frame
e2e/ # Playwright end-to-end tests (React target only for now)
No dependency on an external state framework: the core is headless (no DOM), rendering
lives only in the chosen framework package (today: @flowkit-io/react).
Quickstart
npm install
npm run dev --workspace=@flowkit-io/playground
import { FlowRunner } from "@flowkit-io/react"
import { warmPaper } from "@flowkit-io/themes"
import { createLocalAdapter } from "@flowkit-io/adapters"
import { feedbackFlow } from "@flowkit-io/presets"
import "@flowkit-io/react/style.css"
const adapter = createLocalAdapter()
function App() {
return (
<FlowRunner
flow={feedbackFlow}
theme={warmPaper}
onSubmit={(answers) => adapter.submit(feedbackFlow.id, answers)}
/>
)
}
Shipping only the steps you use
@flowkit-io/react registers all 18 built-in step components, so the snippet above
downloads every one of them even if your flow uses three. When bundle size matters,
@flowkit-io/react/lean exposes the same API and registers nothing: you import the
steps you actually need.
import { FlowRunner } from "@flowkit-io/react/lean"
import "@flowkit-io/react/steps/intro"
import "@flowkit-io/react/steps/text"
import "@flowkit-io/react/steps/confirmation"
Measured on the built output: 11.9 KB gzip for the full entry, 6.0 KB for the lean one
plus those three steps, 4.3 KB with two. FlowRunner throws a descriptive error if it
meets a step type nobody registered, so a forgotten import fails loudly rather than
rendering an empty screen. The main entry is unchanged — this is opt-in.
The map and payment steps were already opt-in for the same reason, since they pull in
maplibre-gl, leaflet or Stripe.js:
import "@flowkit-io/react/map-maplibre" // "location"
import "@flowkit-io/react/map-leaflet" // "location-leaflet"
import "@flowkit-io/react/payment-stripe" // "payment-stripe"
Documentation
Full docs live in docs/:
License
FlowKit 1.0.0 and later is source-available under the
PolyForm Shield License 1.0.0. You may read, modify, redistribute and use it in
production for any purpose except competing with FlowKit or
Flowlab. The license is permanent — it does
not expire and does not convert to an open-source license.
FlowKit 0.x releases remain under the MIT License and are unaffected by
this change. They are legacy and no longer maintained — the new license is
not retroactive. See CHANGELOG.md.
PolyForm Shield 1.0.0 is a source-available license, not an OSI-approved
open-source license.
