Type Alias: ChatViewProps

ChatViewProps = object

Controlled transcript, composer, thread, model, approval, export, and feedback state.

Properties

activeThreadId?

optional activeThreadId?: string

Id of the currently-active thread, highlighted in the sidebar.

className?

optional className?: string

Extra classes merged onto the root layout container.

composerActions?

optional composerActions?: ReactNode

Host-owned controls rendered in the composer footer immediately before the model selector. Use this for per-turn options that belong beside model routing without forking the chat surface.

composerLeadingActions?

optional composerLeadingActions?: ReactNode

Host-owned actions rendered on the left side of the composer’s fixed footer, after Upload and before Export and Clear.

defaultModelId?

optional defaultModelId?: string

Endpoint id behind the unpinned default, used to resolve family and reasoning metadata.

defaultModelLoading?

optional defaultModelLoading?: boolean

True while the server resolves the unpinned agent’s live default model.

defaultModelName?

optional defaultModelName?: string

The serving-endpoint fallback the server uses when no model is pinned, already humanized (the server’s displayName, e.g. “Claude Sonnet 4.6”). When set, the picker’s default option shows this name; otherwise it shows a neutral “Default”. Never a raw endpoint id.

error?

optional error?: Error | null

The error from the last failed turn, surfaced as a destructive Alert when status is "error". When omitted, the Alert shows a generic message. useMastraChat populates it on the drop-in path; a host driving ChatView itself supplies its own.

feedbackByMessage?

optional feedbackByMessage?: Record<string, MessageFeedback>

Feedback state keyed by assistant message id. Only messages with an entry (i.e. a captured MLflow trace id) show feedback controls, so this doubles as the “is feedback available for this message” gate. useMastraChat populates it from each streamed turn’s trace-id response header when MLflow logging is enabled.

hasMore?

optional hasMore?: boolean

True when more history is still available (drives the trigger).

isLoadingHistory?

optional isLoadingHistory?: boolean

True while the initial history page is loading.

isLoadingMore?

optional isLoadingMore?: boolean

True while a ChatViewProps.onLoadMore fetch is in flight.

isLoadingThreads?

optional isLoadingThreads?: boolean

True while the initial thread list is loading (drives a sidebar spinner).

messages

messages: UIMessage[]

mlflowExperimentUrl?

optional mlflowExperimentUrl?: string

Configured MLflow experiment URL for viewers with effective CAN_MANAGE. When present, assistant action rows show a debug link.

model?

optional model?: string

Currently selected model name; empty string means “use server default”.

models?

optional models?: ChatModelOption[]

Available model endpoints. Pass an empty array (or omit) to hide the picker.

modelSelectorActions?

optional modelSelectorActions?: ReactNode

Host-owned controls rendered inside the model selector after the endpoint choices. Omit when the active agent has no matching model-adjacent option.

onCancelThread?

optional onCancelThread?: (threadId) => void

Cancel a thread’s in-flight run by id, without switching to it. When provided, each running sidebar row shows a stop affordance next to its streaming indicator (see streamingThreadIds). Isolated to that thread - other threads keep streaming.

Parameters

threadId

string

Returns

void

onClear?

optional onClear?: () => void | Promise<void>

Wipe the current chat thread. When provided, the header renders a “Clear” button that calls this and shows a confirmation prompt first. The handler is responsible for both the server-side delete (typically mastraClient.clearHistory()) and resetting client-side transcript / tool-event state so the blank slate sticks across the next render. Omit to hide the button entirely (read-only embeds, history-less agents).

Returns

void | Promise<void>

onDeleteThread?

optional onDeleteThread?: (threadId) => void

Delete a conversation by id. The handler removes it server-side and refreshes the list; deleting the active thread starts a new one. When provided, each sidebar row shows a delete affordance.

Parameters

threadId

string

Returns

void

onExportConversation?

optional onExportConversation?: (format) => void | Promise<void>

Export the whole conversation in the chosen ExportFormat (PDF via the browser print dialog, or a Markdown download). When provided, the header shows an Export menu. Charts and data tables are inlined into the export. Omit to hide conversation-level export.

Parameters

format

ExportFormat

Returns

void | Promise<void>

onExportMessage?

optional onExportMessage?: (message, format) => void | Promise<void>

Export a single message in the chosen ExportFormat. When provided, each assistant bubble shows a per-message export menu.

Parameters

message

UIMessage

format

ExportFormat

Returns

void | Promise<void>

onFeedback?

optional onFeedback?: (message, submission) => void | Promise<void>

Submit thumbs / comment feedback for an assistant message. When provided (and the message has a feedbackByMessage entry), the bubble shows thumbs up/down plus a comment affordance. The handler logs the feedback to MLflow via the plugin’s feedback route.

Parameters

message

UIMessage

submission

FeedbackSubmission

Returns

void | Promise<void>

onLoadMore?

optional onLoadMore?: () => void

Optional infinite-scroll-up handler. Fired when the user scrolls within TOP_LOAD_MORE_THRESHOLD_PX of the top of the transcript. The parent is expected to fetch the next older page and prepend it to messages; the view preserves the visual scroll position across the prepend so the reveal feels like paging up through history rather than a layout jump.

Returns

void

onModelChange?

optional onModelChange?: (model) => void

Parameters

model

string

Returns

void

onNewThread?

optional onNewThread?: () => void

Start a fresh conversation. The handler mints a new thread id, clears the transcript, and points subsequent turns at it. When provided, the sidebar shows a “New chat” affordance.

Returns

void

onReasoningEffortChange?

optional onReasoningEffortChange?: (effort) => void

Update the per-turn reasoning effort.

Parameters

effort

ReasoningEffort | undefined

Returns

void

onRemoveSteer?

optional onRemoveSteer?: (steerId) => void

Drop a queued steer without sending it.

Parameters

steerId

string

Returns

void

onRenameThread?

optional onRenameThread?: (threadId, title) => void

Rename a conversation by id. The handler persists the new title server-side and updates the list (optimistically, so the new name shows immediately). When provided, each sidebar row shows a rename affordance that swaps the title into an inline text field.

Parameters

threadId

string

title

string

Returns

void

onReorderSteers?

optional onReorderSteers?: (orderedIds) => void

Reorder the pending steers to match orderedIds (a drag-reorder). The queue then drains - and “send now” fires - in the new order. When provided, queued steer chips become drag-reorderable.

Parameters

orderedIds

string[]

Returns

void

onResolveToolApproval?

optional onResolveToolApproval?: (args) => void | Promise<void>

Resolve an approval-gated tool call. Fired when the user clicks Approve or Deny on the inline approval card. The handler must resume the suspended Mastra workflow on its own: with mastraClient.getAgent(...).stream(), call agent.approveToolCall({ runId, toolCallId }) / agent.declineToolCall({ runId, toolCallId }) to get a fresh stream Response and pipe it through the same chunk handler (this is exactly what useMastraChat does).

It requires the runId Mastra emitted with the approval chunk. useMastraChat also restores run ids from native suspended-run storage when history is reloaded.

Parameters

args

ApprovalDecision

Returns

void | Promise<void>

onSelectThread?

optional onSelectThread?: (threadId) => void

Switch the conversation to threadId. The handler reloads that thread’s history and points subsequent turns at it. Providing this (with threads) is what turns the sidebar on.

Parameters

threadId

string

Returns

void

onSendSteerNow?

optional onSendSteerNow?: (steerId) => void

Fire a queued steer immediately, out of order: interrupt the current turn and start a fresh turn with that steer (removing it from the queue).

Parameters

steerId

string

Returns

void

onStop?

optional onStop?: (threadId?) => void

Abort the in-flight response. When provided and the chat is running (status is "submitted" or "streaming"), the composer swaps the Send button for a Stop button that calls this. The handler should cancel the active generation and return the chat to "ready". Omit to hide the Stop affordance (the Send button just disables while a response streams).

Parameters

threadId?

string

Returns

void

onToggleSidebar?

optional onToggleSidebar?: () => void

Toggle the conversation sidebar’s visibility. Provided alongside sidebarOpen for controlled mode; when omitted the view flips its own internal open state.

Returns

void

pendingApprovalsByMessage?

optional pendingApprovalsByMessage?: Record<string, PendingApproval[]>

Approval requests keyed by assistant message id. This restores persisted suspended runs after a reload and also supports transports that do not surface approvals as UIMessage parts. Entries merge with approvals discovered in message.parts.

queuedSteers?

optional queuedSteers?: QueuedSteer[]

Steers submitted mid-turn that are waiting to run (oldest first). When non-empty the composer shows them as chips above the input, each with a “send now” and a remove action.

reasoningEffort?

optional reasoningEffort?: ReasoningEffort

Optional reasoning effort applied to the next turn. Undefined uses the provider default.

regenerate?

optional regenerate?: () => void

Returns

void

sendMessage

sendMessage: (message) => void

Send a message on the active thread. Submitting while a turn is streaming ENQUEUES the message as a steer (it waits, no interrupt); the queue drains oldest-first when the turn ends. An idle submit starts a turn immediately.

Parameters

message

ChatInputMessage

Returns

void

showThreadBarActions?

optional showThreadBarActions?: boolean

Whether the top tab row renders its built-in New/History controls.

sidebarOpen?

optional sidebarOpen?: boolean

Controlled open/closed state for the conversation sidebar. When omitted the view manages its own (session-only) open state; pass this together with onToggleSidebar to control and persist the show/hide choice from the host (the driver does this so the choice survives reloads). The header toggle is shown whenever the sidebar is enabled, regardless of who owns the state. Only applies to the left / right placements; the top tab strip is always visible.

status

status: ChatStatus

streamingThreadIds?

optional streamingThreadIds?: string[]

Thread ids with an in-flight generation (submitted or streaming). Drives a per-row streaming indicator in the sidebar while a turn continues after the user switches away.

suggestions?

optional suggestions?: string[]

Starter questions shown as one-tap buttons on the empty state. Defaults to none - nothing renders when omitted or empty, so the component carries no built-in example prompts. The drop-in MastraChat fills this from the agent’s Genie space sample questions when the caller doesn’t pass an explicit list.

threadBarActions?

optional threadBarActions?: ReactNode

Host-owned controls appended after the top tab strip’s New and History actions. The persistent assistant uses this for its panel Close button.

threadHistoryIcon?

optional threadHistoryIcon?: ReactNode

Replacement icon for the top tab row’s History action.

threadHistoryLeadingActions?

optional threadHistoryLeadingActions?: ReactNode

Host controls rendered immediately before the top-row History action.

threadNewIcon?

optional threadNewIcon?: ReactNode

Replacement icon for the top tab row’s New action.

threadPlacement?

optional threadPlacement?: ThreadPlacement

Where the conversation list renders (or "disabled" to hide it even when threads and onSelectThread are wired). Defaults to "auto": a right side panel while the chat is wide, a tab strip once it is too narrow for one. See ThreadPlacement.

threads?

optional threads?: ThreadSummary[]

The caller’s conversation threads, newest first. When provided together with onSelectThread, the view renders a collapsible sidebar listing them so the user can switch between conversations. Omit (or pass without onSelectThread) to render the classic single-thread chat with no sidebar.

threadSidebarHeaderActions?

optional threadSidebarHeaderActions?: ReactNode

Host controls rendered in the docked or drawer conversation-list header.

toolEventsByMessage?

optional toolEventsByMessage?: Record<string, ToolEvent[]>