@yak-io/react

React integration for the Yak embeddable chat widget. Provides YakProvider, YakWidget, useYak, and useYakToolEvent.

Installation

pnpm add @yak-io/react

For Next.js, use @yak-io/nextjs instead — it adds route scanning and server handler factories on top of this package.

Quickstart

1. Wrap your app with YakProvider

// src/App.tsx (or your root layout)
import { YakProvider, YakWidget } from "@yak-io/react";

export default function App({ children }: { children: React.ReactNode }) {
  return (
    <YakProvider
      appId={import.meta.env.VITE_YAK_APP_ID}
      theme={{ position: "bottom-right", colorMode: "system" }}
      getConfig={async () => {
        const res = await fetch("/api/yak");
        return res.json();
      }}
      onToolCall={async (name, args) => {
        const res = await fetch("/api/yak", {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify({ name, args }),
        });
        const data = await res.json();
        if (!data.ok) throw new Error(data.error);
        return data.result;
      }}
    >
      {children}
      <YakWidget />
    </YakProvider>
  );
}

2. Control the widget programmatically

import { useYak } from "@yak-io/react";

export function HelpButton() {
  const { open, openWithPrompt, isOpen } = useYak();

  return (
    <div>
      <button onClick={open}>Open Chat</button>
      <button onClick={() => openWithPrompt("How do I get started?")}>
        Get Help
      </button>
      {isOpen && <p>Chat is open</p>}
    </div>
  );
}

3. Invalidate data after tool calls

import { useYakToolEvent } from "@yak-io/react";

function TasksPage() {
  const [tasks, setTasks] = useState([]);

  // Re-fetch when the chatbot modifies tasks
  useYakToolEvent((event) => {
    if (event.ok && event.name.startsWith("tasks.")) {
      fetchTasks().then(setTasks);
    }
  });

  // ...
}

API Reference

YakProvider

Sets up context, initializes the widget, and delegates DOM rendering to @yak-io/javascript.

Props:

| Prop | Type | Required | Description | |------|------|----------|-------------| | appId | string | ✅ | Your Yak app ID | | children | ReactNode | ✅ | Your app content | | getConfig | ChatConfigProvider | — | Async function returning routes + tools config. Called when the widget opens. | | onToolCall | ToolCallHandler | — | Handle tool calls from the assistant | | onGraphQLSchemaCall | GraphQLSchemaHandler | — | Handle GraphQL schema tool calls | | onRESTSchemaCall | RESTSchemaHandler | — | Handle REST/OpenAPI schema tool calls | | theme | Theme | — | Widget theme (position, colorMode, colors) | | onRedirect | (path: string) => void | — | Custom navigation handler (defaults to window.location.assign) | | disableRestartButton | boolean | — | Hide the restart session button | | trigger | boolean \| TriggerButtonConfig | — | Built-in trigger button config (false by default — use <YakWidget> instead) |

YakWidget

Renders a fixed-position launcher button. Place it anywhere inside YakProvider.

Props:

| Prop | Type | Description | |------|------|-------------| | triggerLabel | string | Button label (default: "Ask with AI") | | position | WidgetPosition | Button position (default: "bottom-right") | | colorMode | "light" \| "dark" \| "system" | Color mode override | | lightButton | { background?, color?, border? } | Custom light mode button colors | | darkButton | { background?, color?, border? } | Custom dark mode button colors |

useYak()

Access the widget API from any component inside YakProvider.

const {
  isOpen,      // boolean — whether the widget is open
  isReady,     // boolean — whether the iframe is ready
  open,        // () => void
  close,       // () => void
  openWithPrompt, // (prompt: string) => void
  subscribeToToolEvents, // (handler) => () => void
} = useYak();

Throws if called outside YakProvider.

useYakToolEvent(handler)

Subscribe to tool call completion events. Automatically unsubscribes on unmount. Useful for cache invalidation when the chatbot modifies data.

useYakToolEvent((event) => {
  // event.name   — the tool name called ("tasks.list")
  // event.args   — arguments passed to the tool
  // event.ok     — whether the call succeeded
  // event.result — the result (if ok)
  // event.error  — error message (if not ok)
});

Logging

import { enableYakLogging, disableYakLogging, isYakLoggingEnabled } from "@yak-io/react";

enableYakLogging();    // Enable verbose SDK logs
disableYakLogging();   // Disable SDK logs
isYakLoggingEnabled(); // → boolean

Types

All key types are re-exported for convenience:

import type {
  ChatConfigProvider,
  ToolCallHandler,
  ToolCallEvent,
  GraphQLSchemaHandler,
  RESTSchemaHandler,
  Theme,
  ThemeColors,
  TriggerButtonConfig,
  WidgetPosition,
  SchemaSource,
  GraphQLSchemaSource,
  OpenAPISchemaSource,
} from "@yak-io/react";

License

Proprietary — see LICENSE file.