Props Reference

Complete reference for all Brander component props

Required Props

apiKey

Required

string

Your BranderUX project API key. Must start with bux_pk_. Generate it in your BranderUX dashboard at Projects → API Keys. At runtime the SDK exchanges it for a short-lived token — the raw key never rides the iframe URL.

<Brander apiKey="bux_pk_your_key" projectId="..." onQueryStream={...} />

betaKey

Deprecated

string

Deprecated — use apiKey instead. Legacy bux_dp_ design-partner keys are still accepted during the migration window.

projectId

Required

string

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

<Brander apiKey="..." 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
  apiKey="bux_pk_your_key"
  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
  apiKey="bux_pk_your_key"
  projectId="your_project_id"
  onQueryStream={async function*(params) {
    const stream = anthropic.messages.stream({
      model: "claude-sonnet-5",
      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
  apiKey="bux_pk_your_key"
  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
      apiKey="bux_pk_your_key"
      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
      apiKey="bux_pk_your_key"
      projectId="my-project-id"
      onQueryStream={(params) => sseStream("/api/agent", { params })}
      variant="classic"
      width="100%"
      height="700px"
    />
  );
}