React Hooks

The @stepflowjs/react package provides a set of hooks and a provider to easily integrate Stepflow into your React applications.

Installation

pnpm add @stepflowjs/react @stepflowjs/client

Setup

Wrap your application with the StepflowProvider.

import { StepflowProvider } from "@stepflowjs/react";

function App() {
  return (
    <StepflowProvider
      config={{
        baseUrl: "https://api.your-app.com/stepflow",
        publicApiKey: process.env.NEXT_PUBLIC_STEPFLOW_KEY,
      }}
    >
      <YourComponents />
    </StepflowProvider>
  );
}

Hooks

`useWorkflowTrigger`

Trigger a workflow and manage the resulting run ID and access token.

import { useWorkflowTrigger } from "@stepflowjs/react";

function TriggerButton() {
  const { trigger, isTriggering, runId, accessToken } = useWorkflowTrigger({
    workflowId: "my-workflow",
    onSuccess: (result) => {
      console.log("Triggered!", result.runId);
    },
  });

  return (
    <button disabled={isTriggering} onClick={() => trigger({ some: "data" })}>
      {isTriggering ? "Starting..." : "Start Workflow"}
    </button>
  );
}

`useWorkflowRun`

Subscribe to real-time updates for a specific workflow run.

import { useWorkflowRun } from "@stepflowjs/react";

function WorkflowStatus({ runId, accessToken }) {
  const { run, status, steps, error, isLoading, isConnected } = useWorkflowRun({
    runId,
    accessToken,
    onComplete: (result) => {
      console.log("Finished!", result);
    },
  });

  if (isLoading) return <div>Loading...</div>;

  return (
    <div>
      <h3>
        Status: {status} {isConnected ? "🟢" : "🔴"}
      </h3>
      <ul>
        {steps.map((step) => (
          <li key={step.name}>
            {step.name}: {step.status}
          </li>
        ))}
      </ul>
    </div>
  );
}

`useWorkflowStream`

Trigger and stream events directly in a hook. Useful for AI-like streaming interfaces.

import { useWorkflowStream } from "@stepflowjs/react";

function StreamingComponent() {
  const { start, events, result, isStreaming } = useWorkflowStream({
    workflowId: "generate-text",
    payload: { prompt: "Hello" },
  });

  return (
    <div>
      <button onClick={start} disabled={isStreaming}>
        Start Stream
      </button>

      <div className="events">
        {events.map((event, i) => (
          <div key={i}>{JSON.stringify(event.data)}</div>
        ))}
      </div>

      {result && <div>Final Result: {result}</div>}
    </div>
  );
}

`useStepflow`

Access the underlying StepflowClient instance.

import { useStepflow } from "@stepflowjs/react";

function CustomComponent() {
  const { client } = useStepflow();

  const checkHealth = async () => {
    const { ok } = await client.health();
    console.log("API Status:", ok);
  };

  return <button onClick={checkHealth}>Check Health</button>;
}

React Hooks

On this page