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

ActiveExperienceState | null

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

FirstflowUser

The resolved user your user, or the anonymous fallback.

FirstflowSession

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

CompiledExperience[]

The compiled experiences the provider loaded.

Methods

(id: string) => void

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

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

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

() => void

End the active run and record it dismissed.

(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.

(action, ctx?) => void

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

(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.

() => void

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

(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