Skip to main content

ChatBaseProps

Agent Runtimes

Agent Runtimes / types/chat / ChatBaseProps

Interface: ChatBaseProps

Defined in: src/types/chat.ts:632

ChatBase props

Properties​

agentRuntimeConfig?​

optional agentRuntimeConfig?: AgentRuntimeConfig

Defined in: src/types/chat.ts:838

Simplified agent runtime configuration. A convenience wrapper that creates a ProtocolConfig internally. When provided, will automatically set useStore=false and configure protocol mode.

Example​

<ChatBase
  agentRuntimeConfig={{
    url: 'http://localhost:8765',
    agentId: 'my-agent',
    authToken: 'my-token',
  }}
/>

autoConnect?​

optional autoConnect?: boolean

Defined in: src/types/chat.ts:706

Whether to auto-connect the chat protocol adapter on mount. Defaults to true. Set to false to render the chat shell (header, disabled input, companion notebook/document, launching overlay) without opening a protocol connection — e.g. while the agent runtime endpoint is still being created.

autoFocus?​

optional autoFocus?: boolean

Defined in: src/types/chat.ts:930

Auto-focus the input on mount

availableModels?​

optional availableModels?: ModelConfig[]

Defined in: src/types/chat.ts:741

Override the list of available models. When provided, this list replaces the models returned by the config endpoint. Use this to restrict the model selector to a specific subset of models.

avatarConfig?​

optional avatarConfig?: AvatarConfig

Defined in: src/types/chat.ts:860

Avatar configuration

backgroundColor?​

optional backgroundColor?: string

Defined in: src/types/chat.ts:900

Panel background color

border?​

optional border?: string

Defined in: src/types/chat.ts:903

Border style

borderRadius?​

optional borderRadius?: string | number

Defined in: src/types/chat.ts:897

Border radius for the panel container

boxShadow?​

optional boxShadow?: string

Defined in: src/types/chat.ts:906

Box shadow

brandIcon?​

optional brandIcon?: ReactNode

Defined in: src/types/chat.ts:857

Custom brand icon for header

chatViewMode?​

optional chatViewMode?: ChatViewMode

Defined in: src/types/chat.ts:793

Current chat view mode. When provided, a segmented view-mode toggle is rendered in the header with icons for each mode: floating (popup), floating-small (compact), sidebar (docked).

children?​

optional children?: ReactNode

Defined in: src/types/chat.ts:894

Children to render in the messages area (for custom content)

className?​

optional className?: string

Defined in: src/types/chat.ts:750

Custom class name

codemodeEnabled?​

optional codemodeEnabled?: boolean

Defined in: src/types/chat.ts:725

Indicate tools are accessed via Codemode meta-tools

codemodeStatusData?​

optional codemodeStatusData?: CodemodeStatusData | null

Defined in: src/types/chat.ts:670

External codemode status data. When provided, it is forwarded to AgentDetails so the info panel can render a live codemode status without waiting for the global WebSocket stream.

collapsed?​

optional collapsed?: boolean

Defined in: src/types/chat.ts:1001

Collapse chat panel while keeping the ephemeral notebook visible.

compact?​

optional compact?: boolean

Defined in: src/types/chat.ts:909

Compact mode (reduced padding)

connectedIdentities?​

optional connectedIdentities?: object[]

Defined in: src/types/chat.ts:1051

Connected identities to pass to agent tools. When provided, access tokens for these identities are automatically included in tool calls that need them.

accessToken?​

optional accessToken?: string

provider​

provider: string

userId?​

optional userId?: string

Example​

const { identities, getAccessToken } = useIdentity();
<ChatBase connectedIdentities={identities} />

contextSnapshot?​

optional contextSnapshot?: ContextSnapshotData

Defined in: src/types/chat.ts:656

External context snapshot data for the token usage bar. When provided, this overrides the built-in useContextSnapshot hook (which is a no-op since the REST endpoint was removed). Pass live data received from the monitoring WebSocket.

description?​

optional description?: string

Defined in: src/types/chat.ts:915

Description shown in empty state (protocol mode)

disableInputPrompt?​

optional disableInputPrompt?: boolean

Defined in: src/types/chat.ts:689

Keep input visible but disabled

disableInternalJupyterTheme?​

optional disableInternalJupyterTheme?: boolean

Defined in: src/types/chat.ts:774

Disable ChatBase's internal JupyterReactTheme wrapper. Use this when the host page already provides a JupyterReactTheme boundary.

Default​

false

emptyState?​

optional emptyState?: EmptyStateConfig

Defined in: src/types/chat.ts:872

Empty state configuration

enableEphemeralDocument?​

optional enableEphemeralDocument?: boolean

Defined in: src/types/chat.ts:980

Enable the in-memory "ephemeral document" (Lexical rich-text) companion surface. When enabled it appears as an option in the companion-surface segmented control alongside the notebook.

Default​

false

enableEphemeralNotebook?​

optional enableEphemeralNotebook?: boolean

Defined in: src/types/chat.ts:973

Enable the "Ephemeral Notebook" feature. When true, a toggle is rendered in the input footer that shows/hides an in-memory notebook next to the chat. The notebook model lives purely in memory (never persisted) and is backed by a sandbox kernel. While visible, its frontend tools are registered so the agent can drive the notebook cells.

Default​

true

enableStreaming?​

optional enableStreaming?: boolean

Defined in: src/types/chat.ts:852

Enable streaming mode for custom message handler. When true, will provide streaming callbacks to onSendMessage.

Default​

false

ephemeralNotebookToolbar?​

optional ephemeralNotebookToolbar?: EphemeralNotebookToolbarComponent

Defined in: src/types/chat.ts:1010

Optional toolbar component used by the ephemeral notebook. Defaults to the toolbar from @datalayer/jupyter-react when omitted.

focusTrigger?​

optional focusTrigger?: number

Defined in: src/types/chat.ts:956

Trigger to refocus the input field. When this value changes, the input will be focused. Useful for refocusing after view mode changes.

footerContent?​

optional footerContent?: ReactNode

Defined in: src/types/chat.ts:878

Custom footer content (rendered above input)

frontendTools?​

optional frontendTools?: FrontendToolDefinition<Record<string, unknown>, unknown>[]

Defined in: src/types/chat.ts:962

Frontend tools to register with the agent. These tools execute in the browser and their results are sent back to the agent.

headerActions?​

optional headerActions?: ReactNode

Defined in: src/types/chat.ts:756

Header actions

headerButtons?​

optional headerButtons?: HeaderButtonsConfig

Defined in: src/types/chat.ts:863

Header buttons configuration

headerContent?​

optional headerContent?: ReactNode

Defined in: src/types/chat.ts:891

Custom header content (rendered below title row)

hideMessagesAfterToolUI?​

optional hideMessagesAfterToolUI?: boolean

Defined in: src/types/chat.ts:949

Whether to hide assistant messages that follow a rendered tool call UI. When true, assistant messages after tool UI are hidden to avoid duplicate information.

Default​

false

historyAuthToken?​

optional historyAuthToken?: string

Defined in: src/types/chat.ts:1074

Optional auth token for the legacy history endpoint.

historyEndpoint?​

optional historyEndpoint?: string

Defined in: src/types/chat.ts:1069

Optional legacy endpoint URL for history backfill. History loading is websocket-first; this field is kept for compatibility with custom integrations.

initialEphemeralNotebookOpen?​

optional initialEphemeralNotebookOpen?: boolean

Defined in: src/types/chat.ts:995

Initial open state of the ephemeral notebook toggle. Only relevant when enableEphemeralNotebook is true.

Default​

true

initialEphemeralSurfaceMode?​

optional initialEphemeralSurfaceMode?: EphemeralSurfaceMode

Defined in: src/types/chat.ts:986

Initial companion surface shown next to the chat. Defaults to 'notebook' when enableEphemeralNotebook is true, otherwise 'none'.

initialModel?​

optional initialModel?: string

Defined in: src/types/chat.ts:734

Initial model ID to select (e.g., 'bedrock:us.anthropic.claude-sonnet-4-5-20250929-v1:0')

initialSkills?​

optional initialSkills?: string[]

Defined in: src/types/chat.ts:747

Initial skill IDs to enable

kernel?​

optional kernel?: IKernelConnection | null

Defined in: src/types/chat.ts:766

Live notebook kernel connection. When provided, the chat header renders the same <KernelIndicator> as the notebook toolbar so the colour and tooltip remain in sync with the notebook runtime.

kernelCpu?​

optional kernelCpu?: string

Defined in: src/types/chat.ts:780

Optional CPU info displayed in kernel indicator details.

kernelEnvironmentName?​

optional kernelEnvironmentName?: string

Defined in: src/types/chat.ts:777

Optional environment name displayed in kernel indicator details.

kernelGpu?​

optional kernelGpu?: string

Defined in: src/types/chat.ts:786

Optional GPU info displayed in kernel indicator details.

kernelIndicatorState?​

optional kernelIndicatorState?: ExecutionState

Defined in: src/types/chat.ts:759

Notebook kernel indicator state override for the chat header.

kernelMemory?​

optional kernelMemory?: string

Defined in: src/types/chat.ts:783

Optional memory info displayed in kernel indicator details.

launching?​

optional launching?: boolean

Defined in: src/types/chat.ts:695

Whether the underlying agent runtime is still launching. When true, the chat shell renders with input and controls disabled and a spinner overlay.

launchingMessage?​

optional launchingMessage?: ReactNode

Defined in: src/types/chat.ts:698

Optional message shown next to the spinner while launching is true.

loadingState?​

optional loadingState?: ReactNode

Defined in: src/types/chat.ts:753

Custom loading state

mcpServers?​

optional mcpServers?: McpServerSelection[]

Defined in: src/types/chat.ts:744

MCP servers to enable (others will be disabled)

mcpStatusData?​

optional mcpStatusData?: McpToolsetsStatusResponse | null

Defined in: src/types/chat.ts:663

External MCP toolsets status data for the MCP indicator. When provided, the data is forwarded to the McpStatusIndicator so it shows live status instead of "No MCP Server defined".

onApproveApproval?​

optional onApproveApproval?: (approvalId, note?) => void | Promise<boolean | void>

Defined in: src/types/chat.ts:1140

Called when the user approves a pending request (from banner "Approve All" or from the review dialog).

Parameters​

approvalId​

string

note?​

string

Returns​

void | Promise<boolean | void>

onAuthorizationRequired?​

optional onAuthorizationRequired?: (provider, scopes, context?) => Promise<string | null>

Defined in: src/types/chat.ts:1034

Callback when the agent requests authorization for an external service. This is called when a tool needs OAuth access to a service like GitHub.

Parameters​

provider​

string

The OAuth provider name (e.g., 'github', 'google')

scopes​

string[]

The requested OAuth scopes

context?​

Additional context about why authorization is needed

reason?​

string

toolName?​

string

Returns​

Promise<string | null>

Promise resolving to the access token, or null if user cancels

Example​

<ChatBase
  onAuthorizationRequired={async (provider, scopes, context) => {
    // Show UI to user to authorize
    const token = await showAuthDialog(provider, scopes);
    return token;
  }}
/>

onChatViewModeChange?​

optional onChatViewModeChange?: (mode) => void

Defined in: src/types/chat.ts:798

Callback when the user clicks a different view mode in the header toggle.

Parameters​

mode​

ChatViewMode

Returns​

void

onClear?​

optional onClear?: () => void

Defined in: src/types/chat.ts:924

Callback when messages are cleared

Returns​

void

onEphemeralNotebookOpenChange?​

optional onEphemeralNotebookOpenChange?: (open) => void

Defined in: src/types/chat.ts:998

Controlled callback for ephemeral notebook open-state changes.

Parameters​

open​

boolean

Returns​

void

onEphemeralSurfaceModeChange?​

optional onEphemeralSurfaceModeChange?: (mode) => void

Defined in: src/types/chat.ts:989

Controlled callback for companion surface mode changes.

Parameters​

mode​

EphemeralSurfaceMode

Returns​

void

onExpandFromCollapsed?​

optional onExpandFromCollapsed?: () => void

Defined in: src/types/chat.ts:1004

Callback to reopen chat panel from collapsed notebook mode.

Returns​

void

onInformationClick?​

optional onInformationClick?: () => void

Defined in: src/types/chat.ts:888

Callback when the information icon is clicked

Returns​

void

onMessagesChange?​

optional onMessagesChange?: (messages) => void

Defined in: src/types/chat.ts:927

Callback when messages change (for tracking message count)

Parameters​

messages​

ChatMessage[]

Returns​

void

onNewChat?​

optional onNewChat?: () => void

Defined in: src/types/chat.ts:921

Callback when new chat is triggered

Returns​

void

onRejectApproval?​

optional onRejectApproval?: (approvalId, note?) => void | Promise<boolean | void>

Defined in: src/types/chat.ts:1148

Called when the user rejects a pending request from the review dialog.

Parameters​

approvalId​

string

note?​

string

Returns​

void | Promise<boolean | void>

onSendMessage?​

optional onSendMessage?: MessageHandler

Defined in: src/types/chat.ts:845

Custom message handler (for props-based mode). When provided, uses custom handler instead of store or protocol. Supports streaming via options callbacks.

onStateUpdate?​

optional onStateUpdate?: (state) => void

Defined in: src/types/chat.ts:918

Callback for state updates (for shared state)

Parameters​

state​

unknown

Returns​

void

onToggleCodemode?​

optional onToggleCodemode?: (enabled) => void | Promise<void>

Defined in: src/types/chat.ts:731

Callback fired when the user toggles codemode from the Tools menu. When omitted, the toggle renders in read-only mode.

Parameters​

enabled​

boolean

Returns​

void | Promise<void>

onToolCallComplete?​

optional onToolCallComplete?: (context) => void

Defined in: src/types/chat.ts:1117

Post-hook: fires when a tool result is received. Called for both backend and frontend tools. Use this to react to specific tool outcomes (e.g. update UI state when a load_skill tool completes).

Parameters​

context​

ToolCallCompleteContext

Returns​

void

Example​

<Chat
  onToolCallComplete={({ toolName, result, status }) => {
    if (toolName === 'load_skill' && status === 'complete') {
      // Update skills sidebar from load_skill result
      updateSkillsFromResult(result);
    }
  }}
/>

onToolCallStart?​

optional onToolCallStart?: (context) => void

Defined in: src/types/chat.ts:1097

Pre-hook: fires when a tool call starts executing. Called for both backend and frontend tools.

Parameters​

context​

ToolCallStartContext

Returns​

void

Example​

<Chat
  onToolCallStart={({ toolName, args }) => {
    console.log(`Tool ${toolName} started`, args);
  }}
/>

overlay?​

optional overlay?: ReactNode

Defined in: src/types/chat.ts:713

Optional overlay rendered above the chat surface (messages + input). Use this to show a gating UI such as a sign-in form for anonymous users while keeping the chat visible and its controls disabled behind it.

pendingApprovals?​

optional pendingApprovals?: PendingApproval[]

Defined in: src/types/chat.ts:1134

Pending tool approval requests to render in the built-in banner. Typically sourced from the approvals websocket in the hosting app.

pendingPrompt?​

optional pendingPrompt?: string

Defined in: src/types/chat.ts:1080

A prompt to append and send after the conversation history is loaded. The message is shown in the chat and sent to the agent exactly once.

placeholder?​

optional placeholder?: string

Defined in: src/types/chat.ts:912

Input placeholder override

poweredByProps?​

optional poweredByProps?: Partial<PoweredByTagProps>

Defined in: src/types/chat.ts:869

Powered by tag props

protocol?​

optional protocol?: Protocol | ProtocolConfig

Defined in: src/types/chat.ts:820

Protocol configuration for connecting to backend. When provided and useStore is false, enables protocol mode.

Accepts either a full ProtocolConfig object or a simple Protocol string (e.g. 'vercel-ai'). When a string is provided, it is used as the protocol type and combined with other props (endpoint, agentRuntimeConfig) to build the full configuration.

Default​

'vercel-ai'

renderToolResult?​

optional renderToolResult?: RenderToolResult

Defined in: src/types/chat.ts:875

Tool result renderer for tool calls

runtimeId?​

optional runtimeId?: string

Defined in: src/types/chat.ts:1062

Runtime ID for conversation persistence. When provided, messages are restored from websocket snapshot data on reload and prevents message mixing between different agent runtimes.

sandboxStatusData?​

optional sandboxStatusData?: SandboxWsStatus | null

Defined in: src/types/chat.ts:677

External sandbox status data for the sandbox indicator. When provided, this data is preferred over the indicator's local WebSocket state, which allows optimistic variant updates.

showErrors?​

optional showErrors?: boolean

Defined in: src/types/chat.ts:683

Show error messages

showHeader?​

optional showHeader?: boolean

Defined in: src/types/chat.ts:640

Show header

showInformation?​

optional showInformation?: boolean

Defined in: src/types/chat.ts:885

Show the information icon in the header. When clicked, fires onInformationClick.

Default​

false

showInput?​

optional showInput?: boolean

Defined in: src/types/chat.ts:686

Show input area

showLoadingIndicator?​

optional showLoadingIndicator?: boolean

Defined in: src/types/chat.ts:680

Show loading indicator

showModelSelector?​

optional showModelSelector?: boolean

Defined in: src/types/chat.ts:716

Show model selector (for protocols that support it)

showPoweredBy?​

optional showPoweredBy?: boolean

Defined in: src/types/chat.ts:866

Show powered by tag

showSkillsMenu?​

optional showSkillsMenu?: boolean

Defined in: src/types/chat.ts:722

Show skills menu (for protocols that support it)

showTokenUsage?​

optional showTokenUsage?: boolean

Defined in: src/types/chat.ts:648

Show token usage bar (input/output token counts from the backend). Rendered independently of showHeader, so usage is visible even without a title bar. Requires the protocol to have enableConfigQuery=true and an agentId.

Default​

true

showToolApprovalBanner?​

optional showToolApprovalBanner?: boolean

Defined in: src/types/chat.ts:1128

Whether to render the top-of-chat tool approval banner (and its review dialog) when pendingApprovals is non-empty. The banner/dialog render only when approvals are actually pending; this flag lets integrators opt out entirely.

Default​

true

showToolsMenu?​

optional showToolsMenu?: boolean

Defined in: src/types/chat.ts:719

Show tools menu (for protocols that support it)

submitOnSuggestionClick?​

optional submitOnSuggestionClick?: boolean

Defined in: src/types/chat.ts:942

Whether to automatically submit the message when a suggestion is clicked.

Default​

true

subtitle?​

optional subtitle?: string

Defined in: src/types/chat.ts:637

Chat subtitle (rendered under the title in the header)

suggestions?​

optional suggestions?: Suggestion[]

Defined in: src/types/chat.ts:936

Suggestions to show in empty state. When clicked, the suggestion message is sent to the chat.

title?​

optional title?: string

Defined in: src/types/chat.ts:634

Chat title

useStore?​

optional useStore?: boolean

Defined in: src/types/chat.ts:807

Use Zustand store for state management. When true, uses the shared store. When false with protocol, uses protocol mode.

Default​

true