React component reference

Package: @bootstrapware/onboard
Styles: @bootstrapware/onboard/styles.css

Import styles once near the feature. Use a Client Component in Next.js App Router. Bootstrapware does not authenticate checklist end users. Pass user from your session and workspaceKey for shared steps.

Props

Prop	Type	Required	Notes
user	{ id: string; name?: string }	yes	Opaque stable `id`. Never invent this in production. Wire the real session id.
workspaceKey	string	shared steps	Scopes workspace progress. Bind it on Hosted author tokens when you mint them.
adapter	OnboardAdapter	BYO / local	If set, progress stays on your adapter (or `createLocalAdapter`). Hosted config still loads when `flowId` + `publishableKey` are also set.
items	OnboardChecklistItem[]	Path A	Local checklist. Hosted/BYO typically load items from published flow config.
config	Partial<OnboardFlowConfig>	no	Local merge until hosted config loads. Do not put flowId/items here.
flowId	string	Hosted / BYO config	With publishableKey. Prefix flw_.
publishableKey	string	hosted config	Browser-safe. Never put secret keys in the client.
apiBaseUrl	string	no	Defaults to https://onboard.bootstrapware.co
context	OnboardContext	no	Role, plan, flags for eligibility. Evaluated in the widget. Never send this through MCP.
facts	Record<string, boolean \| string \| number>	no	Sticky reconciliation on mount. Also call `completeStep` from the host when the user actually does the work.
authorToken	string	live Hosted	Short-lived host-signed assertion from `POST /api/v1/author-tokens` (secret key). Required when the flow sets `requireAuthorToken`. Live Hosted without a token is test keys only. Your BFF renews it; the widget never mints.
permissions	OnboardTokenPermission[]	no	Defaults to complete, skip, dismiss, snooze. Include `reset` (and mint it) to show Reset my progress. Reset is personal scope only.
onEvent	(event, payload) => void	BYO side effects	Analytics / CRM. BYO does not emit Bootstrapware webhooks. Payload carries ids, not host context.
focusedAnchor	string	no	Spotlight the item whose anchor matches.
className	string	no	Wrapper class for layout.

Resolve order

Path A — local: createLocalAdapter (or any adapter) plus optional items. Zero keys. Free forever.
Path B — Hosted: omit adapter; pass flowId + publishableKey. Progress lives on Bootstrapware. Live writes need authorToken.
Path C — BYO: pass adapter and flowId + publishableKey so published config still loads. Progress stays on your backend.

Local / demo

import { Onboard, createLocalAdapter, SAAS_FIRST_RUN_ITEMS } from "@bootstrapware/onboard";
import "@bootstrapware/onboard/styles.css";

<Onboard
  user={{ id: session.user.id, name: session.user.name }}
  workspaceKey={workspace.id}
  context={{ role: membership.role, plan: workspace.plan }}
  facts={{ hasBilling: billingConnected }}
  items={SAAS_FIRST_RUN_ITEMS}
  adapter={createLocalAdapter({ storageKey: "demo-onboard" })}
/>

Call completeStep from your app on real actions and pass facts so the widget reconciles on mount. Dismiss hides without 100% progress. Snooze tucks the widget away (default 1 and 7 days).

Hosted

<Onboard
  flowId="flw_..."
  publishableKey={process.env.NEXT_PUBLIC_BSW_ONBOARD_PUBLISHABLE_KEY}
  user={{ id: session.user.id, name: session.user.name }}
  workspaceKey={workspace.id}
  context={{ role: membership.role, plan: workspace.plan }}
  facts={integrationFacts}
  authorToken={authorTokenFromBff}
/>

Live config fetch needs BYO ($9.99) or Hosted ($19.99). Live Hosted writes need Hosted ($19.99). Test publishable keys work unpaid. Auto-renew authorToken from your BFF when expiresAt is within 5 minutes.

Limits in the UI

32 items per flow. 16 eligibility flags per item. See limits.

Related: Modes · Adapter · Identity · Facts · Quickstart