@timbal-ai/timbal-react

React components and runtime for building Timbal chat UIs. Drop in a single component to get a fully-featured streaming chat interface connected to a Timbal workforce agent.

Installation

npm install @timbal-ai/timbal-react
# or
bun add @timbal-ai/timbal-react

Peer dependencies:

npm install react react-dom @assistant-ui/react @timbal-ai/timbal-sdk

Tailwind setup

The package ships pre-built Tailwind class names. Add this @source line to your CSS entry file — without it the components will be unstyled:

/* src/index.css */
@import "tailwindcss";

@source "../node_modules/@timbal-ai/timbal-react/dist";

Adjust the path if your CSS file lives at a different depth relative to node_modules.

CSS imports

Import these stylesheets once in your app entry:

// src/main.tsx
import "@assistant-ui/react-markdown/styles/dot.css";
import "katex/dist/katex.min.css";

Quick start

Basic usage

TimbalChat is a single component that handles everything — runtime, streaming, messages, and the composer:

import { TimbalChat } from "@timbal-ai/timbal-react";

export default function App() {
  return (
    <div style={{ height: "100vh" }}>
      <TimbalChat workforceId="your-workforce-id" />
    </div>
  );
}

TimbalChat requires a fixed height parent. Use height: "100vh" or flex-1 min-h-0 depending on your layout.

Welcome screen and suggestions

<TimbalChat
  workforceId="your-workforce-id"
  welcome={{
    heading: "Hi, I'm your assistant",
    subheading: "Ask me anything about your data.",
  }}
  suggestions={[
    { title: "Summarize this week", description: "Get a quick overview of recent activity" },
    { title: "What can you help with?" },
    { title: "Show me the latest report" },
  ]}
/>

Placeholder and width

<TimbalChat
  workforceId="your-workforce-id"
  composerPlaceholder="Type a question..."
  maxWidth="60rem"
  className="my-custom-class"
/>

Switching agents dynamically

Pass key to fully reset the chat when the workforce changes:

const [workforceId, setWorkforceId] = useState("agent-a");

<select onChange={(e) => setWorkforceId(e.target.value)}>
  <option value="agent-a">Agent A</option>
  <option value="agent-b">Agent B</option>
</select>

<TimbalChat workforceId={workforceId} key={workforceId} />

Splitting the runtime and UI

TimbalChat is a convenience wrapper around TimbalRuntimeProvider + Thread. Use them separately when you need to place the runtime above the chat — for example, to build a custom header that reads or controls chat state:

import { TimbalRuntimeProvider, Thread } from "@timbal-ai/timbal-react";

export default function App() {
  return (
    <TimbalRuntimeProvider workforceId="your-workforce-id">
      <div style={{ height: "100vh", display: "flex", flexDirection: "column" }}>
        <header>My App</header>
        <Thread
          composerPlaceholder="Ask anything..."
          className="flex-1 min-h-0"
        />
      </div>
    </TimbalRuntimeProvider>
  );
}

Custom API base URL

Useful when your API is mounted at a subpath (e.g. behind a reverse proxy):

<TimbalRuntimeProvider workforceId="your-workforce-id" baseUrl="/api">
  <Thread />
</TimbalRuntimeProvider>

Custom fetch function

Pass your own fetch to add headers, inject tokens, or proxy requests:

const myFetch: typeof fetch = (url, options) => {
  return fetch(url, {
    ...options,
    headers: { ...options?.headers, "X-My-Header": "value" },
  });
};

<TimbalRuntimeProvider workforceId="your-workforce-id" fetch={myFetch}>
  <Thread />
</TimbalRuntimeProvider>

Customizing the UI

Use the components prop on TimbalChat or Thread to replace any part of the interface while keeping everything else as the default.

Available slots

| Slot | Props forwarded | Default | |---|---|---| | UserMessage | none | built-in user bubble | | AssistantMessage | none | built-in assistant bubble | | EditComposer | none | built-in inline edit composer | | Composer | placeholder | built-in composer bar | | Welcome | config, suggestions | built-in welcome screen | | ScrollToBottom | none | built-in scroll button |

Custom slot components read their data via hooks — no props are passed automatically except where noted above.

Custom user message

import { TimbalChat, MessagePrimitive } from "@timbal-ai/timbal-react";

const CompactUserMessage = () => (
  <MessagePrimitive.Root className="flex justify-end px-4 py-2">
    <div className="bg-primary text-primary-foreground rounded-2xl px-4 py-2 text-sm max-w-[75%]">
      <MessagePrimitive.Parts />
    </div>
  </MessagePrimitive.Root>
);

<TimbalChat workforceId="..." components={{ UserMessage: CompactUserMessage }} />

Custom composer

The Composer slot receives placeholder from the composerPlaceholder prop:

import { TimbalChat, ComposerPrimitive } from "@timbal-ai/timbal-react";

const MinimalComposer = ({ placeholder }: { placeholder?: string }) => (
  <ComposerPrimitive.Root className="flex items-center gap-2 border rounded-full px-4 py-2">
    <ComposerPrimitive.Input
      placeholder={placeholder ?? "Type here..."}
      className="flex-1 bg-transparent text-sm outline-none"
      rows={1}
    />
    <ComposerPrimitive.Send className="text-primary font-medium text-sm">
      Send
    </ComposerPrimitive.Send>
  </ComposerPrimitive.Root>
);

<TimbalChat workforceId="..." components={{ Composer: MinimalComposer }} />

Custom welcome screen

The Welcome slot is always mounted and controls its own visibility. Use useThread to replicate the default "show only when the thread is empty" behaviour:

import { TimbalChat, useThread, useThreadRuntime, type ThreadWelcomeProps } from "@timbal-ai/timbal-react";

const BrandedWelcome = ({ suggestions }: ThreadWelcomeProps) => {
  const isEmpty = useThread((s) => s.isEmpty);
  const runtime = useThreadRuntime();
  if (!isEmpty) return null;
  return (
    <div className="flex flex-col items-center justify-center h-full gap-4">
      <img src="/logo.svg" className="h-12" />
      <h2 className="text-xl font-semibold">Welcome to Acme AI</h2>
      <div className="flex gap-2 flex-wrap justify-center">
        {suggestions?.map((s) => (
          <button
            key={s.title}
            onClick={() => runtime.append({ role: "user", content: [{ type: "text", text: s.title }] })}
            className="border rounded-full px-4 py-1.5 text-sm hover:bg-muted"
          >
            {s.title}
          </button>
        ))}
      </div>
    </div>
  );
};

<TimbalChat
  workforceId="..."
  suggestions={[{ title: "Get started" }, { title: "Show me an example" }]}
  components={{ Welcome: BrandedWelcome }}
/>

Mixing slots

Override any combination — slots are independent of each other:

<TimbalChat
  workforceId="..."
  components={{
    UserMessage: CompactUserMessage,
    Composer: MinimalComposer,
  }}
/>

Hooks and primitives

These are re-exported from @assistant-ui/react for use inside custom slot components:

| Export | Use inside | |---|---| | ThreadPrimitive | Any slot | | MessagePrimitive | UserMessage, AssistantMessage, EditComposer | | ComposerPrimitive | Composer, EditComposer | | ActionBarPrimitive | UserMessage, AssistantMessage | | useThread | Any slot — subscribe to thread state (e.g. isRunning, isEmpty) | | useThreadRuntime | Any slot — call actions (e.g. runtime.append(...)) | | useMessageRuntime | UserMessage, AssistantMessage — edit, reload, branch | | useComposerRuntime | Composer, EditComposer — access composer state |

API reference

TimbalChat props

TimbalChat accepts all TimbalRuntimeProvider props plus all Thread props.

| Prop | Type | Default | Description | |---|---|---|---| | workforceId | string | required | ID of the workforce to stream from | | baseUrl | string | "/api" | Base URL for API calls. Posts to {baseUrl}/workforce/{workforceId}/stream | | fetch | (url, options?) => Promise<Response> | authFetch | Custom fetch. Defaults to the built-in auth-aware fetch (Bearer token + auto-refresh) | | welcome.heading | string | "How can I help you today?" | Welcome screen heading | | welcome.subheading | string | "Send a message to start a conversation." | Welcome screen subheading | | suggestions | { title: string; description?: string }[] | — | Suggestion chips on the welcome screen | | composerPlaceholder | string | "Send a message..." | Composer input placeholder | | components | ThreadComponents | — | Override individual UI slots | | maxWidth | string | "44rem" | Max width of the message column | | className | string | — | Extra classes on the root element |

Thread props

Same as TimbalChat minus workforceId, baseUrl, and fetch (those live on TimbalRuntimeProvider).

TimbalRuntimeProvider props

| Prop | Type | Default | Description | |---|---|---|---| | workforceId | string | required | ID of the workforce to stream from | | baseUrl | string | "/api" | Base URL for API calls | | fetch | (url, options?) => Promise<Response> | authFetch | Custom fetch function |

Auth

The package includes an optional session/auth system backed by localStorage tokens. The API is expected to expose /api/auth/login, /api/auth/logout, and /api/auth/refresh.

Auth is opt-in — it only activates when VITE_TIMBAL_PROJECT_ID is set in your environment.

Setup

Wrap your app with SessionProvider and protect routes with AuthGuard:

// src/App.tsx
import { SessionProvider, AuthGuard, TooltipProvider } from "@timbal-ai/timbal-react";
import { BrowserRouter, Routes, Route } from "react-router-dom";
import Home from "./pages/Home";

const isAuthEnabled = !!import.meta.env.VITE_TIMBAL_PROJECT_ID;

export default function App() {
  return (
    <SessionProvider enabled={isAuthEnabled}>
      <TooltipProvider>
        <BrowserRouter>
          <AuthGuard requireAuth enabled={isAuthEnabled}>
            <Routes>
              <Route path="/" element={<Home />} />
            </Routes>
          </AuthGuard>
        </BrowserRouter>
      </TooltipProvider>
    </SessionProvider>
  );
}

When enabled is false, both SessionProvider and AuthGuard are transparent — no redirects, no API calls.

useSession hook

Access the current session anywhere inside SessionProvider:

import { useSession } from "@timbal-ai/timbal-react";

function Header() {
  const { user, isAuthenticated, loading, logout } = useSession();
  if (loading) return null;
  return (
    <header>
      {isAuthenticated ? (
        <>
          <span>{user?.email}</span>
          <button onClick={logout}>Log out</button>
        </>
      ) : (
        <a href="/login">Log in</a>
      )}
    </header>
  );
}

authFetch

A drop-in replacement for fetch that attaches the Bearer token from localStorage and auto-refreshes on 401. It's also the default fetch used by TimbalRuntimeProvider, so you only need to import it directly for your own API calls (e.g. loading workforce lists):

import { authFetch } from "@timbal-ai/timbal-react";

const res = await authFetch("/api/workforce");
if (res.ok) {
  const agents = await res.json();
}

Auth prop reference

| Component | Prop | Type | Default | Description | |---|---|---|---|---| | SessionProvider | enabled | boolean | true | When false, session is always null and no API calls are made | | AuthGuard | requireAuth | boolean | false | Redirect to login if not authenticated | | AuthGuard | enabled | boolean | true | When false, renders children unconditionally |

Other exports

Components

| Export | Description | |---|---| | Thread | Full chat UI — messages, composer, attachments, action bar | | MarkdownText | Markdown renderer with GFM, math (KaTeX), and syntax highlighting | | ToolFallback | Animated "Using tool: …" indicator shown while a tool runs | | SyntaxHighlighter | Shiki-based code highlighter (vitesse-dark / vitesse-light themes) | | UserMessageAttachments | Attachment thumbnails in user messages | | ComposerAttachments | Attachment previews inside the composer | | ComposerAddAttachment | "+" button to add attachments | | TooltipIconButton | Icon button with a tooltip |

UI primitives

Re-exported Radix UI wrappers pre-styled to match the Timbal design system:

Button · Tooltip · TooltipTrigger · TooltipContent · TooltipProvider · Avatar · AvatarImage · AvatarFallback · Dialog · DialogContent · DialogTitle · DialogTrigger · Shimmer

Full example

A complete page with agent switching, auth, and a custom header:

// src/pages/Home.tsx
import { useEffect, useState } from "react";
import type { WorkforceItem } from "@timbal-ai/timbal-sdk";
import { TimbalChat, Button, authFetch, useSession } from "@timbal-ai/timbal-react";
import { LogOut } from "lucide-react";

const isAuthEnabled = !!import.meta.env.VITE_TIMBAL_PROJECT_ID;

export default function Home() {
  const { logout } = useSession();
  const [workforces, setWorkforces] = useState<WorkforceItem[]>([]);
  const [selectedId, setSelectedId] = useState("");

  useEffect(() => {
    authFetch("/api/workforce")
      .then((r) => r.json())
      .then((data: WorkforceItem[]) => {
        setWorkforces(data);
        const agent = data.find((w) => w.type === "agent") ?? data[0];
        if (agent) setSelectedId(agent.id ?? agent.name ?? "");
      })
      .catch(() => {});
  }, []);

  return (
    <div style={{ display: "flex", flexDirection: "column", height: "100vh" }}>
      <header style={{ display: "flex", justifyContent: "space-between", padding: "0.5rem 1.25rem" }}>
        <select value={selectedId} onChange={(e) => setSelectedId(e.target.value)}>
          {workforces.map((w) => (
            <option key={w.id ?? w.name} value={w.id ?? w.name ?? ""}>
              {w.name}
            </option>
          ))}
        </select>

        {isAuthEnabled && (
          <Button variant="ghost" size="icon" onClick={logout}>
            <LogOut />
          </Button>
        )}
      </header>

      <TimbalChat
        workforceId={selectedId}
        key={selectedId}
        className="flex-1 min-h-0"
        welcome={{ heading: "How can I help you today?" }}
      />
    </div>
  );
}

Local development

Install via a local path reference:

{
  "dependencies": {
    "@timbal-ai/timbal-react": "file:../../timbal-react"
  }
}

Adjust the relative path to where timbal-react lives on your machine.

After editing source files, rebuild:

cd timbal-react
bun run build        # one-off build
bun run build:watch  # rebuild on every change

Vite picks up the new dist/ automatically via HMR — no reinstall needed.