TrueForgeUI

import { TrueForgeUI } from "@truefoundry/trueforge-ui";

Properties

TrueForgeServerConfig

required

Where the chat gets its data. Either a built-in config object or a ready AgentUIServer.

Show TrueForgeServerConfig

"trueforge"

Omit entirely to pass an AgentUIServer object directly — there is no "custom" wrapper. "trueforge" loads the Harness adapter (plugins/trueforge-agent-server-adapter). See Quickstart.

string

TrueForge / Harness API root. Used when type is "trueforge". Defaults to '/'.

string

Bearer token for @truefoundry/trueforge-sdk when type is "trueforge". Prefer fetch for cookie / OIDC hosts.

typeof fetch

Custom fetch for type: "trueforge" (cookie sessions, auth interceptors).

CatalogServer

Attach or override settings catalogs. See Settings catalog.

PermissionsServer

Override the built-in permissions port.

See Server contract.

LayoutProp

required

A built-in layout name or your own component.

Show LayoutProp

BuiltInLayout

Full-page chat with a persistent thread list.

BuiltInLayout

Thread list collapses into an overlay drawer.

BuiltInLayout

Right-pinned panel, capped at 400px. Stacks list and thread.

Floating launcher expanding into a compact panel.

ComponentType<{ className?: string }>

Your own component, rendered inside the full provider stack.

See Layouts.

AgentConfig

default:"{ mode: \"AgentLibraryWithComposer\" }"

Which agent-selection surfaces the shell exposes.

Show AgentConfig

variant

Pins the UI to one named agent. name is required; selection controls are hidden.

variant

Users pick from saved agents. New chat is disabled in this mode only.

variant

Users assemble an ad-hoc agent.

variant

Both surfaces. The default.

defaultAgentSpec seeds a new draft and is picked up on new chat, not on clear chat. See Agent modes.

ThemeConfig

Preset, color mode, tokens, branding, and content class names.

Show ThemeConfig

"trueforge" | "claude" | "chatgpt" | "gemini"

default:"\"trueforge\""

Base token palette.

"light" | "dark" | "system"

Omit for uncontrolled — the SDK resolves system and persists the user’s choice to localStorage under aui-theme-preference. Passing a value makes it controlled and turns setTheme into a no-op.

Partial<SemanticTokens>

Per-token overrides, merged over the preset and applied as inline styles.

Show SemanticTokens

string

sidebarBg, sidebarText, topbarBg, primaryBg, secondaryBg, border, fontFamily (maps to --font-agent-ui).

string

inputBoxBg, inputBorder, textPrimary, textSecondary, cardBg, dropdownSelectedItemBg, dropdownSelectedItemText.

string

userMessageBg, userMessageText, assistantMessageBg, assistantMessageText.

string

primaryButtonBg / primaryButtonHover / primaryButtonText, and the same trio for secondaryButton* and ghostButton*.

string

successBg / successText, failureBg / failureText, warningBg / warningText.

string

focusRing, radius, composerRadius, overlay, shadowColor, scrollbarThumb.

BrandConfig

Optional. Omit it to use the built-in TrueForge wordmark in expanded chrome and square mark in compact surfaces. When set, choose mode first, then pass the fields that mode requires.

Show BrandConfig

"icon-title" | "icon-only" | "logo"

Chrome look. icon-title shows name beside the square mark; icon-only and logo keep name for alt only.

string

Required. Accessible image label (alt / aria-label). Also shown as title text beside the square icon when mode is icon-title.

string | BrandLogoConfig

Square image used in collapsed and compact surfaces. Optional for icon-title (default mark); required for icon-only and logo.

string | BrandLogoConfig

Wider image used when mode is logo. Falls back to icon in BrandLogo if needed. Required for mode: "logo".

string

Wraps configured brand images in a same-tab link.

Show BrandLogoConfig

string

Source used when the resolved mode is light.

string

Source used when the resolved mode is dark.

string

Mode-agnostic source, used when neither light nor dark is set.

A single configured mode is used for both modes, so { light } alone never renders a missing image. Use BrandLogo with variant="icon" or variant="logo" in custom layouts. To render a component rather than an image, override its slot through overrides.

IconMap

Replace registry icons by name. Values are Lucide components, React nodes, render functions, or SVGR components.

ContentClassNames

Host CSS classes for content renderers. See Custom Theme — Styling rendered content.

Show ContentClassNames

string

Root of the markdown renderer (joins .aui-markdown).

string

Inline code spans inside markdown.

{ root?, pre?, code?, lineNumber? }

Fenced non-OpenUI code blocks (joins .aui-syntax-highlighter on root).

{ root?, scope? }

Generative UI fence blocks (root joins .aui-openui; scope is the OpenUI theme selector).

{ root?, editor?, monacoTheme? }

Monaco editor wrapper (root joins .aui-monaco), mount container (editor), and optional Monaco theme name (monacoTheme).

string

Applied to the theme root wrapper.

See Theming.

SlotOverrides

Replace any built-in component. Partial<AtomSlots>, derived from the SDK’s default slot table — so editor autocomplete lists the overridable names. See Slot overrides.

string

Passed to the layout component, and to the loading and error states. Typically "h-full min-h-0". To style the theme wrapper instead, use theme.className.

string

Open an existing session on mount instead of starting fresh.

RuntimeAdapters

Runtime adapter overrides. Attachments default to trueForgeAttachmentAdapter.

(error: unknown) => void

Called when the server fails to resolve or the runtime raises an error.

Behavior notes

The component mounts every provider it needs, so you do not have to wrap it in anything. Switching agents, starting a new draft, or clearing the chat resets the conversation — the current transcript is cleared so that one agent’s messages do not carry into another’s context. Persisted sessions remain available through the thread list.

If window.location.search contains screenType=mcp-auth, the component renders only the OAuth completion screen and no layout. See MCP OAuth.

Example

<TrueForgeUI
  server={{ type: "trueforge", baseUrl, token }}
  layout="sidebar"
  agentConfig={{ mode: "AgentComposer", defaultAgentSpec: { model: { name: "openai-main/gpt-4.1" } } }}
  theme={{
    preset: "claude",
    brand: { mode: "logo", name: "Acme", icon: "/icon.svg", logo: "/wordmark.svg" },
  }}
  overrides={{ ClearChatButton: MyClearButton }}
  className="h-full min-h-0"
  onError={(e) => reportError(e)}
/>

Getting Started

TrueForge Harness

SDK

UI Chat

Project

Properties

Behavior notes

Example

​Properties

​Behavior notes

​Example

Properties

Behavior notes

Example