React SDK

The @yak-io/react package provides React components and hooks for integrating Yak into any React application.

For Next.js applications, use @yak-io/nextjs instead for automatic route scanning and App Router integration.

Installation

npm install @yak-io/react @yak-io/javascript

pnpm add @yak-io/react @yak-io/javascript

yarn add @yak-io/react @yak-io/javascript

bun add @yak-io/react @yak-io/javascript

Quick Start

// App.tsx
import { YakProvider, YakWidget } from "@yak-io/react";

export default function App() {
  return (
    <YakProvider
      appId="your-app-id"
      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;
      }}
    >
      {/* Your app content */}
      <YakWidget />
    </YakProvider>
  );
}

Set up server handlers

Use @yak-io/javascript to create the API endpoints on your backend. See the JavaScript SDK for runtime-specific examples (Express, Hono, Cloudflare Workers, etc.).

// api/yak.ts
import { createYakHandler } from "@yak-io/javascript/server";

export const { GET, POST } = createYakHandler({
  routes: [
    { path: "/", title: "Home" },
    { path: "/products", title: "Products" },
  ],
});

Components

YakProvider

Wraps your application and manages widget state and communication.

Prop	Type	Required	Description
`appId`	`string`	Yes	Your Yak application ID
`getConfig`	`() => Promise<ChatConfig>`	No	Config provider for routes and tools
`onToolCall`	`(name, args) => Promise<unknown>`	No	Handler for tool execution
`theme`	`Theme`	No	Widget styling options
`onRedirect`	`(path: string) => void`	No	Custom navigation handler
`disableRestartButton`	`boolean`	No	Hide the restart button in the header

YakWidget

Renders the floating chat button and panel.

Prop	Type	Default	Description
`iframeClassName`	`string`	—	CSS class for the iframe
`triggerLabel`	`string`	`"Ask with AI"`	Text on the floating button

Hooks

useYak

Access widget controls from any component inside YakProvider:

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

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

  return (
    <div>
      <button onClick={() => open()}>Open Chat</button>
      <button onClick={() => openWithPrompt("Help me with this page")}>
        Get Help
      </button>
      {isOpen && <button onClick={() => close()}>Close</button>}
    </div>
  );
}

Property	Type	Description
`open`	`() => void`	Open the chat panel
`close`	`() => void`	Close the chat panel
`openWithPrompt`	`(prompt: string) => void`	Open and send a specific prompt
`isOpen`	`boolean`	Whether the chat panel is currently open

useYakToolEvent

Subscribe to tool call completion events — useful for keeping your UI in sync with agent actions:

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

function OrderPage({ orderId }: { orderId: string }) {
  const queryClient = useQueryClient();

  useYakToolEvent((event) => {
    if (event.ok && event.name.startsWith("order.")) {
      queryClient.invalidateQueries({ queryKey: ["order", orderId] });
    }
  });

  return <OrderDetails orderId={orderId} />;
}

See UI Synchronization for more details.

Router Integration

Pass your framework's navigation function to onRedirect for client-side navigation:

// React Router
import { useNavigate } from "react-router-dom";

function App() {
  const navigate = useNavigate();

  return (
    <YakProvider onRedirect={(path) => navigate(path)} {...props}>
      {children}
    </YakProvider>
  );
}

// TanStack Router
<YakProvider onRedirect={(path) => router.navigate({ to: path })} />

Next Steps

Styling — Customize appearance, position, and colors
Programmatic Control — Open widget from code, context-sensitive help
UI Synchronization — Keep your UI in sync with agent actions
Tool Adapters — Connect your APIs as tools