Props Reference

Complete reference for all Brander component props

Required Props

betaKey

Required

string

Your BranderUX API token. Must start with bux_. Get this from your BranderUX dashboard at Settings → API Keys.

<Brander betaKey="bux_abc123xyz" projectId="..." onQueryStream={...} />

projectId

Required

string

Your BranderUX project ID. Get this from your BranderUX dashboard. Each project has its own configuration, branding, and data sources.

<Brander betaKey="..." projectId="your_project_id" onQueryStream={...} />

AI Handler (ONE of the following)

You must provide either onQueryStream (recommended) or onQuery. BranderUX instructions are included in params.messages — simply pass them directly to your AI provider.

onQueryStream

Recommended

StreamingCallback

Streaming AI handler using AG-UI events. Provides progressive UI loading for the best user experience. Use with stream adapters: sseStream, anthropicStream, openaiStream, geminiStream.

Function Signature:

type StreamingCallback = (
  params: CustomerAIParams
) => AsyncIterable<AGUIEvent> | ReadableStream<AGUIEvent>;

Usage with sseStream (Most Common):

import Brander, { sseStream } from "@brander/sdk";

<Brander
  betaKey="bux_your_token"
  projectId="your_project_id"
  onQueryStream={(params) => sseStream("/api/agent", { params })}
/>

Usage with Provider Adapters:

import Brander, { anthropicStream } from "@brander/sdk";
import Anthropic from "@anthropic-ai/sdk";

const anthropic = new Anthropic({ apiKey: "..." });

<Brander
  betaKey="bux_your_token"
  projectId="your_project_id"
  onQueryStream={async function*(params) {
    const stream = anthropic.messages.stream({
      model: "claude-sonnet-4-20250514",
      messages: params.messages,
      tools: params.tools.anthropic,
    });
    yield* anthropicStream(stream);
  }}
/>

onQuery

Alternative

OnQueryCallback

Non-streaming AI handler. Returns complete response at once. Use for simple integrations that don't need streaming.

Non-streaming provides a less responsive UX. Consider streaming for production use.

Function Signature:

type OnQueryCallback = (
  params: CustomerAIParams
) => Promise<CustomerAIResponse>;

Usage:

import Brander from "@brander/sdk";

<Brander
  betaKey="bux_your_token"
  projectId="your_project_id"
  onQuery={async (params) => {
    const response = await fetch("/api/ai", {
      method: "POST",
      body: JSON.stringify(params),
    });
    return response.json();
  }}
/>

CustomerAIParams (passed to your handler)

interface CustomerAIParams {
  system?: string;             // System instructions (A2UI protocol in flexible mode)
  messages: Array<{
    role: "user" | "assistant";
    content: string;
  }>;
  tools?: MultiProviderTools;  // Screen tools in all provider formats
  max_tokens?: number;         // Suggested max tokens
}

// Tools provided in all provider formats
interface MultiProviderTools {
  anthropic: AnthropicTool[];  // Use with Anthropic Claude
  openai: OpenAITool[];        // Use with OpenAI GPT
  gemini: GeminiTool[];        // Use with Google Gemini
}

Optional Props

Prop	Type	Default	Description
variant	`"hybrid" \| "classic" \| "chat"`	`"chat"`	Display variant: hybrid (full playground), classic (site-focused), chat (inline messages)
defaultSidebarOpen	`boolean`	`true`	Default state of conversation sidebar in classic variant
conversations	`Conversation[]`	`undefined`	Initial conversations to load for persistence
activeConversationId	`string`	`undefined`	ID of currently active conversation
onConversationsChange	`function`	`undefined`	Callback when conversation state changes
width	`string`	`"100%"`	Widget container width
height	`string`	`"600px"`	Widget container height
className	`string`	`undefined`	CSS class for container
style	`CSSProperties`	`undefined`	Inline styles for container

Conversation Persistence

Use the conversation props to persist chat history across sessions:

import Brander, { sseStream } from "@brander/sdk";
import { useState, useEffect } from "react";

function App() {
  const [conversations, setConversations] = useState([]);
  const [activeId, setActiveId] = useState(null);

  // Load from storage on mount
  useEffect(() => {
    const saved = localStorage.getItem("brander_conversations");
    if (saved) {
      const state = JSON.parse(saved);
      setConversations(state.conversations);
      setActiveId(state.activeConversationId);
    }
  }, []);

  return (
    <Brander
      betaKey="bux_your_token"
      projectId="your_project_id"
      onQueryStream={(params) => sseStream("/api/agent", { params })}
      conversations={conversations}
      activeConversationId={activeId}
      onConversationsChange={(state) => {
        setConversations(state.conversations);
        setActiveId(state.activeConversationId);
        localStorage.setItem("brander_conversations", JSON.stringify(state));
      }}
    />
  );
}

Complete Example

App.tsx

import Brander, { sseStream } from "@brander/sdk";

function App() {
  return (
    <Brander
      betaKey="bux_your_token"
      projectId="my-project-id"
      onQueryStream={(params) => sseStream("/api/agent", { params })}
      variant="classic"
      width="100%"
      height="700px"
    />
  );
}