usePrompt

React adapter for @web-ai-sdk/prompt. Runs single-shot prompts on demand via ask(input) and exposes status, streaming output text, and abort / reset controls. For the conceptual overview of the underlying API see Prompt.

Before shipping, review the Production checklist for intent-driven preparation, safe streaming, progress, user control, and cache freshness.

To warm the session before the hook first runs, call prepareLanguageModel from the core package on user intent. See the Session lifecycle guide.

Live demo

Type a question and click “Ask”. Tokens stream in as the model produces them. Click “Cancel” to abort mid-stream.

Usage

import { usePrompt } from "@web-ai-sdk/prompt/react";

export function AskBox() {
  const { status, output, error, ask, abort } = usePrompt({
    systemPrompt: "You are a helpful assistant. Be concise.",
    samplingMode: "balanced",
  });

  if (status === "unavailable") return null;

  return (
    <form
      onSubmit={(e) => {
        e.preventDefault();
        const input = new FormData(e.currentTarget).get("q") as string;
        if (input) ask(input);
      }}
    >
      <input name="q" placeholder="Ask anything" />
      <button type="submit" disabled={status === "loading" || status === "streaming"}>
        {status === "streaming" ? "Streaming…" : "Ask"}
      </button>
      {output && <p>{output}</p>}
      {error && <small>{error.message}</small>}
    </form>
  );
}

The hook doesn’t auto-run on mount; you call ask(input) from a form submit, button click, or any event. Each call cancels any in-flight request and starts a fresh one.

State machine

idle ───► loading ───► streaming ───► done
                                       │
unavailable ◄─── (no flag / no model)  │
                                       ▼
                                    reset() / abort()

• idle: ready. Call ask(input) to start.
• loading: warming the LanguageModel.create() session (~1-3s cold start).
• streaming: chunks arriving. output grows on each chunk; render it directly for a typewriter effect.
• done: final output in output. fromCache is true if the result came from the opt-in result cache (i.e. you passed cache and a prior call wrote to it).
• unavailable: API missing. Render nothing or a fallback.

abort() cancels the current request and flips status back to idle. reset() clears the output and returns to idle without touching any in-flight request.

Stable options

Pass cache, expectedInputs, etc. as stable references. The hook keeps the latest options in a ref so the ask callback stays stable across renders without restarting on every render.

Streaming UX

output updates on every chunk during streaming. A naive <p>{output}</p> already produces a typewriter effect because React re-renders on each state change. If chunks arrive faster than you want to repaint, debounce on the consumer side.

Multi-turn

usePrompt is single-shot per ask(). For multi-turn conversation where each chat needs independent context, use useSession — it returns a per-component, never-shared LanguageModel session with send, sendStreaming, abort, clone, destroy, contextWindow, contextUsage, and onContextOverflow. Keep message history and clearing behavior in your own component state.

Reference

import type { UsePromptOptions, UsePromptReturn, PromptStatus } from "@web-ai-sdk/prompt/react";

type PromptStatus = "idle" | "loading" | "streaming" | "done" | "unavailable";

interface UsePromptOptions extends Omit<AskOptions, "input" | "onUpdate" | "signal"> {
  // Inherited from AskOptions (subset shown — see Prompt guide):
  systemPrompt?: string;
  samplingMode?: "most-predictable" | "predictable" | "balanced" | "creative" | "most-creative";
  temperature?: number;
  topK?: number;
  language?: string;
  supportedLanguages?: readonly string[];
  expectedInputs?: LanguageModelExpectedInput[];
  expectedOutputs?: LanguageModelExpectedOutput[];
  responseConstraint?: object;        // JSON Schema for structured output
  monitor?: (m: CreateMonitor) => void;
  cache?: "session" | "local" | { get, set };
  cacheKey?: string;
  cacheTtl?: number;                  // built-in shortcut TTL in ms; default 1 hour
  cacheRefresh?: boolean;             // skip the cache read, write the fresh result
}

interface UsePromptReturn {
  status: PromptStatus;
  output: string | null;
  error: Error | null;
  fromCache: boolean;
  ask(input: string): Promise<void>;  // cancels any in-flight request first
  abort(): void;                      // cancel in-flight; status becomes "idle"
  reset(): void;                      // clear output without aborting
}

declare const usePrompt: (options?: UsePromptOptions) => UsePromptReturn;

Source: packages/prompt/src/react/index.ts.