useFirstflow

useFirstflow() returns the current runtime state and the methods to drive it. Use it to trigger experiences from your own UI, build a custom shell, or react to the active step. It must be called inside FirstflowProvider.

import { useFirstflow } from "@firstflow/runtime";

function Launcher() {
  const { startExperience, active } = useFirstflow();
  return (
    <button disabled={!!active} onClick={() => startExperience("exp_welcome")}>
      Show onboarding
    </button>
  );
}

State

active

ActiveExperienceState | null

The running experience and its position (experience, currentNodeId, history, answers), or null when nothing is showing.

user

FirstflowUser

The resolved user your user, or the anonymous fallback.

session

FirstflowSession

Auto-tracked session context (url, locale, deviceType, startedAt) used by audience conditions.

experiences

CompiledExperience[]

The compiled experiences the provider loaded.

Methods

startExperience

(id: string) => void

Start an experience by id (bypasses triggers). No-op if the id is unknown.

advance

(answer?: { questionId, value }) => void

Advance the active run to the next visible node, optionally recording an answer.

dismiss

() => void

End the active run and record it dismissed.

emit

(eventName: string) => void

Fire a custom event triggers any experience with a matching custom_event trigger. The standalone emitCustomEvent(name) does the same from outside the provider.

executeAction

(action, ctx?) => void

Run a single compiled action (next, submit, dismiss, link, event, prompt, minimize). Used by the default blocks.

executeActions

(actions, ctx?) => void

Run an ordered list of actions for one interaction. Non-terminal actions (link/event/prompt/minimize) run in author order; the single terminal action (next/submit/dismiss) runs last.

minimize

() => void

Collapse the widget shell to its resting state without ending the run.

registerMinimizeHandler

(fn) => () => void

Persistence interface

Pass any object implementing FirstflowPersistence to the provider. Implement it for a non-Supabase backend:

interface FirstflowPersistence {
  loadInProgress(userId: string): Promise<InProgressRun[]>;
  hasCompleted(userId: string, experienceId: string): Promise<boolean>;
  recordStart(userId, experienceId, state): Promise<{ runId: string }>;
  recordProgress(runId: string, state): Promise<void>;
  recordEnd(runId: string, status: "completed" | "dismissed"): Promise<void>;
}

loadInProgress runs once on mount (for resume); recordProgress fires on every transition; recordEnd fires on completion or dismissal. All writes are fire-and-forget failures are logged, never thrown.

Custom launcher with events

const { emit } = useFirstflow();
// elsewhere, after an LLM reply classifies the intent:
if (intent === "billing") emit("show_billing_help"); // fires the matching trigger

Build a custom shell, handle events, or wire the server SDK classifier to drive emit.

Browser SDK

Server SDK

Advanced

State

Methods

Persistence interface

Custom launcher with events

Next

​State

​Methods

​Persistence interface

​Custom launcher with events

​Next

State

Methods

Persistence interface

Custom launcher with events

Next