Register tools and artifacts

Pass tool renderers, data renderers and artifact kinds to ChatProvider. Registration uses exact, case-sensitive kind values. The composer’s / commands, @ mention sources and features go there too; see Composer commands.

import { ChatProvider } from '@frogbotai/ui/chat'
import type { ArtifactRendererProps } from '@frogbotai/ui/chat/artifacts'
import { cookieFetch, createRestChatAdapter } from '@frogbotai/ui/chat/rest'
import type { ToolRendererProps } from '@frogbotai/ui/chat/tools'

const adapter = createRestChatAdapter({ fetch: cookieFetch() })

function SearchResult({ part }: ToolRendererProps) {
  return <pre>{JSON.stringify('output' in part ? part.output : part.input, null, 2)}</pre>
}

function Chart({ artifact }: ArtifactRendererProps) {
  return <pre>{JSON.stringify(artifact.content, null, 2)}</pre>
}

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <ChatProvider
      adapter={adapter}
      toolRenderers={[{ kind: 'search', render: SearchResult }]}
      artifactKinds={[{ kind: 'chart', render: Chart }]}
    >
      {children}
    </ChatProvider>
  )
}

Tool kinds without a registration use the generic tool card: a closed card with a wrench icon, the tool’s name and a one-line summary of its input. While the call runs the icon is a spinner; when it finishes the icon turns green, and a failed or denied call turns it red and starts the title with Failed: or Denied:. Opening it shows the input, then the output, error or denial reason, scrolling past 240px. An output in MCP’s CallToolResult shape, { content: [...] }, shows its { type: 'text', text } items as text and its { type: 'image', data, mimeType } items with an image/* type as images, in order; anything else shows as JSON. Artifact kinds without a registration show their title, kind, and serialized content rather than throwing.

Tool cards

toolCard(kind, describe) returns a tool renderer that draws each call of kind as the same card, with your own icon, title and body. describe gets the call’s part and returns what the card shows:

import { toolCard } from '@frogbotai/ui/chat/tools'

const search = toolCard('web_search', (part) => ({
  icon: 'web',
  title: part.state === 'output-available' ? 'Searched the web' : 'Searching the web',
  subtitle: (part.input as { query?: string } | undefined)?.query,
  links:
    part.state === 'output-available'
      ? (part.output as { results: { url: string; title: string }[] }).results
      : undefined,
}))

<ChatProvider adapter={adapter} toolRenderers={[search]} />

Field	Type	Description
`icon`	`IconName`	The tool’s icon, by its name in FrogBot’s icon set, such as `web`, `cursor` or `keyboard`.
`title`	`ReactNode`	The card’s title. Failed and denied calls add Failed: or Denied: in front.
`subtitle`	`ReactNode`	Muted text after the title, cut off with an ellipsis when it doesn’t fit.
`links`	`LinkListItem[]`	Rows of links, shown first in the body. See Link lists.
`body`	`ReactNode`	Anything else the card opens to.

A card with no links or body has no chevron and doesn’t open. The card’s status comes from the part’s state: running until the call has an output, then done, error or denied. To draw the card yourself, for example inside your own renderer, use ToolCard. It takes icon, status ('running' | 'done' | 'error' | 'denied'), title, subtitle and the body as children, plus Radix Collapsible’s open, defaultOpen and onOpenChange.

Link lists

LinkList shows rows of links, each with the site’s icon, the page’s title, its host and an optional snippet. Every row opens in a new tab.

import { LinkList } from '@frogbotai/ui/chat/tools'

<LinkList
  items={[
    { url: 'https://frogs.example/tree-frogs', title: 'Tree frogs', snippet: 'A care guide.' },
  ]}
/>

Field	Type	Description
`url`	`string`	The page. Its host, without `www.`, shows after the title.
`title`	`string`	The page’s title.
`snippet`	`string`	Up to two lines of text under the title.

Site icons come from ChatProvider’s faviconUrl. Without it, each row shows the host’s first letter and no request leaves the page.

Tool renderer options

Option	Type	Default	Description
`kind`	`string`	Required	Tool name to render, matched exactly against the call’s tool name, such as `question`.
`render`	`ComponentType<ToolRendererProps>`	Required	Component that renders the call.

The component receives:

Prop	Type	Description
`part`	`DynamicToolUIPart \| ToolUIPart`	The tool call part, with its `state`, `input`, and either `output` or `errorText`.
`addToolOutput`	`(output: unknown) => Promise<void>`	Set only while a client tool call waits for an answer. Submits the answer.
`dismiss`	`() => Promise<void>`	Set only while a client tool call waits for an answer. Declines the call.
`isReadonly`	`boolean`	`true` in a read-only conversation.
`channelLabel`	`string`	The channel’s name in a read-only conversation, such as `Slack`.

Data renderer options

A data-<kind> message part uses the first dataRenderers entry whose kind matches. Parts without one show their JSON payload. data-paste, data-page-context and data-prompt keep FrogBot’s own rendering.

Option	Type	Default	Description
`kind`	`string`	Required	The part type without its `data-` prefix, matched exactly, such as `compaction` for `data-compaction`.
`render`	`ComponentType<{ part: DataPartValue }>`	Required	Component that renders the part. It receives `part` (`{ type, data, id? }`).

CompactionPart is the built-in renderer for a chat compaction. It isn’t registered by default:

import { ChatProvider, CompactionPart } from '@frogbotai/ui/chat'

<ChatProvider adapter={adapter} dataRenderers={[{ kind: 'compaction', render: CompactionPart }]}>
  {children}
</ChatProvider>

It reads CompactionPartData:

Field	Type	Description
`status`	`'running' \| 'completed' \| 'failed'`	Where the compaction is.
`reason`	`'auto' \| 'manual'`	Why it ran.
`summary`	`string`	The summary, shown as Markdown between a “Compaction started” and a “Chat compacted” divider.
`error`	`string`	Shown under “Compaction failed”.
`tokens`	`{ input: number, output: number }`	The summary call’s usage, shown as `12K in · 1.2K out` on the closing divider. Left out when missing or zero.

While status is running, it shows Compacting… with a spinner and no closing divider. Data in any other shape shows as JSON. SteeredPart renders a data-steered part, a message the user steered into a running reply, as a user bubble where the reply took it. Register it as { kind: 'steered', render: SteeredPart }. It reads SteeredPartData, { messageId: string, text: string }; data in any other shape shows as JSON.

Artifact options

Option	Type	Default	Description
`kind`	`string`	Required	Artifact kind, matched exactly against `artifact.kind`. A `data-<kind>` stream part is routed to the same registration.
`render`	`ComponentType<ArtifactRendererProps>`	Required	Component that renders the artifact. It receives `artifact` (`{ kind, content, id?, title? }`) and `setArtifact`.
`initialize`	`() => Artifact`	—	Creates the artifact before the first stream part is applied, when none is open.
`onStreamPart`	`({ setArtifact, streamPart }) => void`	—	Applies each matching `data-<kind>` part to the open artifact.
`description`	`string`	—	Accepted but not rendered by the built-in components.
`actions`	`ReactNode[]`	—	Accepted but not rendered by the built-in components.
`toolbar`	`ReactNode[]`	—	Accepted but not rendered by the built-in components.

artifactPersistence on ChatProvider takes:

Option	Type	Default	Description
`load`	`(id: string) => Promise<Artifact \| undefined>`	Required	Loads an artifact by ID when an artifact viewer opens it.
`save`	`(artifact: Artifact) => Promise<Artifact>`	Required	Saves the open artifact when the viewer’s Save button is clicked, then shows the returned artifact.

Composer commands

commands, mentionSources, composerFeatures and composerHistory on ChatProvider extend the composer, in <Chat> or a standalone Composer.

'use client'

import {
  ChatProvider,
  type ComposerCommand,
  type ComposerFeature,
  defaultComposerFeatures,
  type MentionSource,
} from '@frogbotai/ui/chat'
import { useLexicalComposerContext } from '@frogbotai/ui/lexical'
import { useEffect } from 'react'

const commands: ComposerCommand[] = [
  { id: 'new', title: 'New chat', execute: () => startNewChat() },
  { id: 'model', title: 'Switch model', arguments: true, execute: (name) => selectModel(name) },
]

const pages: MentionSource = {
  id: 'pages',
  search: async (query, { signal }) => {
    const response = await fetch(`/api/pages?search=${encodeURIComponent(query)}`, { signal })
    const { docs } = await response.json()

    return docs.map((page: { id: string; title: string; url: string }) => ({
      id: page.id,
      label: page.title,
      data: { url: page.url },
    }))
  },
}

function SaveDraft() {
  const [editor] = useLexicalComposerContext()

  useEffect(
    () => editor.registerTextContentListener((text) => sessionStorage.setItem('draft', text)),
    [editor],
  )

  return null
}

const features: ComposerFeature[] = [...defaultComposerFeatures, { key: 'draft', plugin: SaveDraft }]

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <ChatProvider
      adapter={adapter}
      commands={commands}
      mentionSources={[pages]}
      composerFeatures={features}
    >
      {children}
    </ChatProvider>
  )
}

Typing / as the whole input opens a menu of the enabled commands whose id or title contains the text after it. Typing @ at the start or after a space searches every mention source and groups the results by source. In both menus Tab or Enter picks, Up and Down or Ctrl+N and Ctrl+P move, and Escape closes the menu. Picking a command without arguments clears the input and runs it. Picking one with arguments writes /id ; sending /id rest then calls execute(rest). Either way the text clears, attachments stay, nothing is sent or added to history, and it works while a reply streams. In <Chat>, a command that rejects shows Command failed: <message>. Picking a mention inserts a chip that reads @label. One Backspace removes it. <Chat> sends the chip’s @label in the text and a data-mention part for it; see Composer prompt. Up in an empty input recalls the last sent prompt, chips included; Up and Down then page through the list while the caret is at the start or end, and Down past the newest empties the input. FrogBot keeps 100 prompts, newest first, without repeating the newest. Commands and attachments are not kept. Import Lexical from @frogbotai/ui/lexical, which re-exports lexical and useLexicalComposerContext, so a feature uses the composer’s own copy.

Command options

Option	Type	Default	Description
`id`	`string`	Required	Typed after `/`, such as `model` for `/model`.
`title`	`string`	Required	Shown in the menu, and matched like `id`.
`description`	`string`	—	Shown after the title.
`arguments`	`boolean`	`false`	The command takes the text after `/id` .
`disabled`	`boolean`	`false`	Leaves the command out of the menu and out of `/id rest`.
`queue`	`boolean`	`false`	While a reply runs, the command waits in the chat’s queue as its `/` text instead of running at once.
`execute`	`(input: string) => void \| Promise<void>`	Required	Runs the command with the text after `/id` , or `''`.

Mention source options

Option	Type	Default	Description
`id`	`string`	Required	Names the source; the menu groups its results under it, and each chip records it as `source`.
`search`	`(query: string, options: { signal: AbortSignal }) => MentionItem[] \| Promise<MentionItem[]>`	Required	Returns the items for the text after `@`. The next keystroke aborts `signal`. A source that rejects adds no results.

Mention item options

Option	Type	Default	Description
`id`	`string`	Required	Identifies the item within its source.
`label`	`string`	Required	Shown in the menu; the chip reads `@label`.
`description`	`string`	—	Shown after the label.
`icon`	`ReactNode`	—	Shown before the label.
`data`	`Record<string, unknown>`	—	Sent with the chip in its `data-mention` part.

Composer feature options

defaultComposerFeatures holds slash, mentions, paste, history and keybindings. A composerFeatures list replaces it, and the last feature with a key wins, so [...defaultComposerFeatures, { key: 'history' }] turns prompt history off. Editing a sent message uses only mentions and keybindings.

Option	Type	Default	Description
`key`	`string`	Required	Names the feature.
`nodes`	`Klass<LexicalNode>[]`	—	Lexical nodes the feature uses, registered when the editor is created.
`plugin`	`ComponentType`	—	Rendered inside the editor, where `useLexicalComposerContext()` returns it.

Composer history storage options

The default keeps the list in localStorage under frogbot:composer-history, and loads an empty list from data it can’t read. Errors from load and save are ignored.

Option	Type	Default	Description
`load`	`() => ComposerPrompt[] \| Promise<ComposerPrompt[]>`	Required	Returns the stored prompts, newest first. Called once when a composer mounts.
`save`	`(entries: ComposerPrompt[]) => void \| Promise<void>`	Required	Stores the list after each send that adds to it.

Answer client tools

A renderer for a client tool receives addToolOutput(output) and dismiss() while its call is waiting for an answer in the latest assistant message. addToolOutput submits the answer, and the chat resubmits once every call in the step has one. dismiss declines the call without calling the model again. Both props are absent while the reply is streaming and for calls that were already answered, so render the part read-only when they are missing. QuestionToolRender is the built-in renderer for the question tool. Custom chat surfaces that render ToolPart outside Chat can supply the same actions through ToolActionsContext.

Read-only conversations

In a channel conversation, Chat is read-only, and every tool renderer receives isReadonly: true and channelLabel instead of the answer callbacks. addToolOutput and dismiss are never passed, even for a call that is still waiting. Use channelLabel, such as Slack, for copy like “Waiting for an answer in Slack”.

import type { ToolRendererProps } from '@frogbotai/ui/chat/tools'

function PickFileCard({ addToolOutput, channelLabel, isReadonly, part }: ToolRendererProps) {
  if (part.state !== 'input-available') return <PickedFile part={part} />

  if (isReadonly) return <p>Waiting for an answer in {channelLabel}</p>

  const { files } = part.input as { files: string[] }

  return <FilePicker files={files} onPick={(file) => addToolOutput?.({ file })} />
}

Custom surfaces set isReadonly and channelLabel on ToolActionsContext to get the same behavior. Add initialize and onStreamPart to an artifact registration when data parts progressively build an artifact. Add artifactPersistence to ChatProvider to provide application-specific load and save functions.

Start here

Basics

Managing Data

Features

Ecosystem

Deployment

Register tools and artifacts

Tool cards

Link lists

Tool renderer options

Data renderer options

Artifact options

Composer commands

Command options

Mention source options

Mention item options

Composer feature options

Composer history storage options

Answer client tools

Read-only conversations

​Tool cards

​Link lists

​Tool renderer options

​Data renderer options

​Artifact options

​Composer commands

​Command options

​Mention source options

​Mention item options

​Composer feature options

​Composer history storage options

​Answer client tools

​Read-only conversations

Tool cards

Link lists

Tool renderer options

Data renderer options

Artifact options

Composer commands

Command options

Mention source options

Mention item options

Composer feature options

Composer history storage options

Answer client tools

Read-only conversations