Skip to main content

ChatCommonProps

Agent Runtimes

Agent Runtimes / types/chat / ChatCommonProps

Interface: ChatCommonProps

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

Common props shared by all Chat wrapper components (Chat, ChatFloating, ChatSidebar, ChatStandalone, ChatPopupStandalone).

These props represent the public API surface that consumers interact with. Wrapper components forward most of them to ChatBase and translate others (e.g. showNewChatButton → headerButtons.showNewChat).

Each wrapper extends this interface with component-specific props (e.g. position, defaultOpen, width for floating variants).

Use panelProps as an escape hatch to pass any ChatBase prop not directly surfaced in this interface.

Extended by​

Properties​

authToken?​

optional authToken?: string

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

Auth token for the agent runtime

autoFocus?​

optional autoFocus?: boolean

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

Auto-focus the input on mount

availableModels?​

optional availableModels?: ModelConfig[]

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

Override the list of available models. When provided, replaces models returned by the config endpoint.

brandIcon?​

optional brandIcon?: ReactNode

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

Custom brand icon for header / empty state

chatViewMode?​

optional chatViewMode?: ChatViewMode

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

Current chat view mode for header segmented toggle

children?​

optional children?: ReactNode

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

Children to render in the messages area

className?​

optional className?: string

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

Custom class name

codemodeEnabled?​

optional codemodeEnabled?: boolean

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

Indicate tools are accessed via Codemode meta-tools

codemodeStatusData?​

optional codemodeStatusData?: CodemodeStatusData | null

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

External codemode status data (e.g. from WebSocket stream).

collapsed?​

optional collapsed?: boolean

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

Collapse chat panel while keeping the ephemeral notebook visible.

contextSnapshot?​

optional contextSnapshot?: ContextSnapshotData

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

External context snapshot data for the token usage bar

description?​

optional description?: string

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

Description shown in empty state

disableInputPrompt?​

optional disableInputPrompt?: boolean

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

Keep input visible but disabled

disableInternalJupyterTheme?​

optional disableInternalJupyterTheme?: boolean

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

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

Default​

false

enableEphemeralDocument?​

optional enableEphemeralDocument?: boolean

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

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:453

Show an in-memory "ephemeral notebook" next to the chat, toggled from the input footer. The notebook model lives purely in memory (never persisted) and its frontend tools are registered while visible.

Default​

true

enableStreaming?​

optional enableStreaming?: boolean

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

Enable streaming mode for custom message handler.

Default​

false

ephemeralNotebookToolbar?​

optional ephemeralNotebookToolbar?: EphemeralNotebookToolbarComponent

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

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

frontendTools?​

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

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

Frontend tool definitions to register with the chat

headerActions?​

optional headerActions?: ReactNode

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

Custom header actions (rendered in title row, right side)

headerContent?​

optional headerContent?: ReactNode

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

Custom header content (rendered below title row)

hideMessagesAfterToolUI?​

optional hideMessagesAfterToolUI?: boolean

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

Hide assistant messages that follow a rendered tool call UI.

Default​

false

historyAuthToken?​

optional historyAuthToken?: string

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

Optional auth token for the legacy history endpoint

historyEndpoint?​

optional historyEndpoint?: string

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

Optional legacy endpoint URL for fetching conversation history

initialEphemeralNotebookOpen?​

optional initialEphemeralNotebookOpen?: boolean

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

Initial open state of the ephemeral notebook.

Default​

true

initialEphemeralSurfaceMode?​

optional initialEphemeralSurfaceMode?: EphemeralSurfaceMode

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

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:426

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:438

Initial skill IDs to enable

kernel?​

optional kernel?: IKernelConnection | null

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

Live kernel connection of the companion notebook/document sandbox. When provided, it is forwarded to the chat header's <KernelIndicator> so the indicator reflects the surface's runtime.

launching?​

optional launching?: boolean

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

Whether the underlying agent runtime is still launching. When true, the chat shell is rendered with the input and controls disabled and a spinner overlay is shown, so the plain chat view appears as soon as the agent starts being created and stays interactive-disabled until it is ready.

launchingMessage?​

optional launchingMessage?: ReactNode

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

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

mcpServers?​

optional mcpServers?: McpServerSelection[]

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

MCP server selections to enable (others disabled)

mcpStatusData?​

optional mcpStatusData?: McpToolsetsStatusResponse | null

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

External MCP toolsets status data

onApproveApproval?​

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

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

Called when the user approves a pending request.

Parameters​

approvalId​

string

note?​

string

Returns​

void | Promise<boolean | void>

onChatViewModeChange?​

optional onChatViewModeChange?: (mode) => void

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

Callback when user switches chat view mode

Parameters​

mode​

ChatViewMode

Returns​

void

onClose?​

optional onClose?: () => void

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

Callback when the component closes

Returns​

void

onEphemeralNotebookOpenChange?​

optional onEphemeralNotebookOpenChange?: (open) => void

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

Controlled callback for ephemeral notebook open-state changes.

Parameters​

open​

boolean

Returns​

void

onEphemeralSurfaceModeChange?​

optional onEphemeralSurfaceModeChange?: (mode) => void

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

Controlled callback for companion surface mode changes.

Parameters​

mode​

EphemeralSurfaceMode

Returns​

void

onExpandFromCollapsed?​

optional onExpandFromCollapsed?: () => void

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

Callback to reopen chat panel from collapsed notebook mode.

Returns​

void

onInformationClick?​

optional onInformationClick?: () => void

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

Callback when the information icon is clicked

Returns​

void

onNewChat?​

optional onNewChat?: () => void

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

Callback when new chat is triggered

Returns​

void

onOpen?​

optional onOpen?: () => void

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

Callback when the component opens

Returns​

void

onRejectApproval?​

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

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

Called when the user rejects a pending request.

Parameters​

approvalId​

string

note?​

string

Returns​

void | Promise<boolean | void>

onSendMessage?​

optional onSendMessage?: MessageHandler

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

Custom message handler. When provided, uses this handler instead of protocol mode.

onSettingsClick?​

optional onSettingsClick?: () => void

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

Callback when settings is clicked

Returns​

void

onStateUpdate?​

optional onStateUpdate?: (state) => void

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

Callback for state updates

Parameters​

state​

unknown

Returns​

void

onToggleCodemode?​

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

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

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:493

Post-hook: fires when a tool result is received

Parameters​

context​

ToolCallCompleteContext

Returns​

void

onToolCallStart?​

optional onToolCallStart?: (context) => void

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

Pre-hook: fires when a tool call starts executing

Parameters​

context​

ToolCallStartContext

Returns​

void

overlay?​

optional overlay?: ReactNode

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

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.

panelProps?​

optional panelProps?: Partial<ChatBaseProps>

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

Additional ChatBase props (escape hatch). Props set here are spread onto ChatBase as overrides.

pendingApprovals?​

optional pendingApprovals?: PendingApproval[]

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

Pending tool approval requests to render in the top banner.

pendingPrompt?​

optional pendingPrompt?: string

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

A prompt to send after conversation history is loaded (sent once).

placeholder?​

optional placeholder?: string

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

Input placeholder

poweredByProps?​

optional poweredByProps?: Partial<PoweredByTagProps>

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

Powered by tag props

protocol?​

optional protocol?: Protocol | ProtocolConfig

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

Protocol type or full configuration.

When a Protocol string is provided (e.g. 'vercel-ai'), it is forwarded to ChatBase. When a full ProtocolConfig object is provided, it is used directly.

Default​

'vercel-ai'

renderToolResult?​

optional renderToolResult?: RenderToolResult

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

Custom render function for tool results

runtimeId?​

optional runtimeId?: string

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

Runtime ID for conversation persistence

sandboxStatusData?​

optional sandboxStatusData?: SandboxWsStatus | null

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

Optional sandbox status override for immediate UI updates.

showClearButton?​

optional showClearButton?: boolean

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

Show clear button in header

showHeader?​

optional showHeader?: boolean

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

Show header

showInformation?​

optional showInformation?: boolean

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

Show the information icon in the header.

Default​

false

showInput?​

optional showInput?: boolean

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

Show input area

showModelSelector?​

optional showModelSelector?: boolean

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

Show model selector

showNewChatButton?​

optional showNewChatButton?: boolean

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

Show new chat button in header

showPoweredBy?​

optional showPoweredBy?: boolean

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

Show powered by tag

showSettingsButton?​

optional showSettingsButton?: boolean

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

Show settings button in header

showSkillsMenu?​

optional showSkillsMenu?: boolean

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

Show skills menu

showTokenUsage?​

optional showTokenUsage?: boolean

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

Show token usage bar.

Default​

true

showToolApprovalBanner?​

optional showToolApprovalBanner?: boolean

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

Whether to render the top-of-chat tool approval banner when there are pending approvals.

Default​

true

showToolsMenu?​

optional showToolsMenu?: boolean

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

Show tools menu

submitOnSuggestionClick?​

optional submitOnSuggestionClick?: boolean

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

Whether to auto-submit when a suggestion is clicked.

Default​

true

subtitle?​

optional subtitle?: string

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

Chat subtitle (rendered under the title in the header)

suggestions?​

optional suggestions?: Suggestion[]

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

Suggestions to show in empty state

title?​

optional title?: string

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

Chat title

useStore?​

optional useStore?: boolean

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

Use Zustand store for state management instead of protocol endpoint.

Default​

true