> ## Documentation Index
> Fetch the complete documentation index at: https://trueforge.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# TrueForgeUI

> The entry component and every prop it accepts.

```tsx theme={null}
import { TrueForgeUI } from "@truefoundry/trueforge-ui";
```

## Properties

<ParamField path="server" type="TrueForgeServerConfig" required>
  Where the chat gets its data. Either a built-in config object or a ready `AgentUIServer`.

  <Expandable title="TrueForgeServerConfig">
    <ParamField path="type" type="&#x22;trueforge&#x22;">
      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](/ui-sdk/get-started/quickstart).
    </ParamField>

    <ParamField path="baseUrl" type="string">
      TrueForge / Harness API root. Used when `type` is `"trueforge"`. Defaults to `'/'`.
    </ParamField>

    <ParamField path="token" type="string">
      Bearer token for `@truefoundry/trueforge-sdk` when `type` is `"trueforge"`. Prefer `fetch` for
      cookie / OIDC hosts.
    </ParamField>

    <ParamField path="fetch" type="typeof fetch">
      Custom fetch for `type: "trueforge"` (cookie sessions, auth interceptors).
    </ParamField>

    <ParamField path="catalog" type="CatalogServer">
      Attach or override settings catalogs. See [Settings catalog](/ui-sdk/reference/catalog).
    </ParamField>

    <ParamField path="permissions" type="PermissionsServer">
      Override the built-in permissions port.
    </ParamField>
  </Expandable>

  See [Server contract](/ui-sdk/setup-custom-servers/server-contract).
</ParamField>

<ParamField path="layout" type="LayoutProp" required>
  A built-in layout name or your own component.

  <Expandable title="LayoutProp">
    <ParamField path="&#x22;sidebar&#x22;" type="BuiltInLayout">
      Full-page chat with a persistent thread list.
    </ParamField>

    <ParamField path="&#x22;drawer&#x22;" type="BuiltInLayout">
      Thread list collapses into an overlay drawer.
    </ParamField>

    <ParamField path="&#x22;dock&#x22;" type="BuiltInLayout">
      Right-pinned panel, capped at 400px. Stacks list and thread.
    </ParamField>

    <ParamField path="&#x22;widget&#x22;" type="BuiltInLayout">
      Floating launcher expanding into a compact panel.
    </ParamField>

    <ParamField path="Custom" type="ComponentType<{ className?: string }>">
      Your own component, rendered inside the full provider stack.
    </ParamField>
  </Expandable>

  See [Layouts](/ui-sdk/guides/layouts).
</ParamField>

<ParamField path="agentConfig" type="AgentConfig" default="{ mode: &#x22;AgentLibraryWithComposer&#x22; }">
  Which agent-selection surfaces the shell exposes.

  <Expandable title="AgentConfig">
    <ParamField path="{ mode: &#x22;SingleAgent&#x22;; name: string }" type="variant">
      Pins the UI to one named agent. `name` is required; selection controls are hidden.
    </ParamField>

    <ParamField path="{ mode: &#x22;AgentLibrary&#x22; }" type="variant">
      Users pick from saved agents. New chat is disabled in this mode only.
    </ParamField>

    <ParamField path="{ mode: &#x22;AgentComposer&#x22;; defaultAgentSpec?: AgentSpec }" type="variant">
      Users assemble an ad-hoc agent.
    </ParamField>

    <ParamField path="{ mode: &#x22;AgentLibraryWithComposer&#x22;; defaultAgentSpec?: AgentSpec }" type="variant">
      Both surfaces. The default.
    </ParamField>
  </Expandable>

  `defaultAgentSpec` seeds a new draft and is picked up on new chat, not on clear chat. See
  [Agent modes](/ui-sdk/concepts/agent-modes).
</ParamField>

<ParamField path="theme" type="ThemeConfig">
  Preset, color mode, tokens, branding, and content class names.

  <Expandable title="ThemeConfig">
    <ParamField path="preset" type="&#x22;trueforge&#x22; | &#x22;claude&#x22; | &#x22;chatgpt&#x22; | &#x22;gemini&#x22;" default="&#x22;trueforge&#x22;">
      Base token palette.
    </ParamField>

    <ParamField path="mode" type="&#x22;light&#x22; | &#x22;dark&#x22; | &#x22;system&#x22;">
      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.
    </ParamField>

    <ParamField path="tokens" type="Partial<SemanticTokens>">
      Per-token overrides, merged over the preset and applied as inline styles.

      <Expandable title="SemanticTokens">
        <ParamField path="Across product" type="string">
          `sidebarBg`, `sidebarText`, `topbarBg`, `primaryBg`, `secondaryBg`, `border`, `fontFamily`
          (maps to `--font-agent-ui`).
        </ParamField>

        <ParamField path="Building blocks" type="string">
          `inputBoxBg`, `inputBorder`, `textPrimary`, `textSecondary`, `cardBg`,
          `dropdownSelectedItemBg`, `dropdownSelectedItemText`.
        </ParamField>

        <ParamField path="Chat" type="string">
          `userMessageBg`, `userMessageText`, `assistantMessageBg`, `assistantMessageText`.
        </ParamField>

        <ParamField path="Buttons" type="string">
          `primaryButtonBg` / `primaryButtonHover` / `primaryButtonText`, and the same trio for
          `secondaryButton*` and `ghostButton*`.
        </ParamField>

        <ParamField path="Status" type="string">
          `successBg` / `successText`, `failureBg` / `failureText`, `warningBg` / `warningText`.
        </ParamField>

        <ParamField path="Kept internals" type="string">
          `focusRing`, `radius`, `composerRadius`, `overlay`, `shadowColor`, `scrollbarThumb`.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField path="brand" type="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.

      <Expandable title="BrandConfig">
        <ParamField path="mode" type="&#x22;icon-title&#x22; | &#x22;icon-only&#x22; | &#x22;logo&#x22;">
          Chrome look. `icon-title` shows `name` beside the square mark; `icon-only`
          and `logo` keep `name` for alt only.
        </ParamField>

        <ParamField path="name" type="string">
          Required. Accessible image label (`alt` / `aria-label`). Also shown as title
          text beside the square icon when `mode` is `icon-title`.
        </ParamField>

        <ParamField path="icon" type="string | BrandLogoConfig">
          Square image used in collapsed and compact surfaces. Optional for
          `icon-title` (default mark); required for `icon-only` and `logo`.
        </ParamField>

        <ParamField path="logo" type="string | BrandLogoConfig">
          Wider image used when `mode` is `logo`. Falls back to `icon` in
          `BrandLogo` if needed. Required for `mode: "logo"`.
        </ParamField>

        <ParamField path="href" type="string">
          Wraps configured brand images in a same-tab link.
        </ParamField>
      </Expandable>

      <Expandable title="BrandLogoConfig">
        <ParamField path="light" type="string">
          Source used when the resolved mode is light.
        </ParamField>

        <ParamField path="dark" type="string">
          Source used when the resolved mode is dark.
        </ParamField>

        <ParamField path="src" type="string">
          Mode-agnostic source, used when neither `light` nor `dark` is set.
        </ParamField>
      </Expandable>

      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`.
    </ParamField>

    <ParamField path="icons" type="IconMap">
      Replace registry icons by name. Values are Lucide components, React nodes, render
      functions, or SVGR components.
    </ParamField>

    <ParamField path="classNames" type="ContentClassNames">
      Host CSS classes for content renderers. See [Custom Theme — Styling rendered content](/ui-sdk/setup-custom-ui/custom-theme).

      <Expandable title="ContentClassNames">
        <ParamField path="markdown" type="string">
          Root of the markdown renderer (joins `.aui-markdown`).
        </ParamField>

        <ParamField path="inlineCode" type="string">
          Inline code spans inside markdown.
        </ParamField>

        <ParamField path="syntaxHighlighter" type="{ root?, pre?, code?, lineNumber? }">
          Fenced non-OpenUI code blocks (joins `.aui-syntax-highlighter` on `root`).
        </ParamField>

        <ParamField path="openui" type="{ root?, scope? }">
          Generative UI fence blocks (`root` joins `.aui-openui`; `scope` is the OpenUI theme selector).
        </ParamField>

        <ParamField path="monaco" type="{ root?, editor?, monacoTheme? }">
          Monaco editor wrapper (`root` joins `.aui-monaco`), mount container (`editor`), and optional Monaco theme name (`monacoTheme`).
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField path="className" type="string">
      Applied to the theme root wrapper.
    </ParamField>
  </Expandable>

  See [Theming](/ui-sdk/setup-custom-ui/custom-theme).
</ParamField>

<ParamField path="overrides" type="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](/ui-sdk/setup-custom-ui/slot-overrides).
</ParamField>

<ParamField path="className" type="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`.
</ParamField>

<ParamField path="initialSessionId" type="string">
  Open an existing session on mount instead of starting fresh.
</ParamField>

<ParamField path="adapters" type="RuntimeAdapters">
  Runtime adapter overrides. Attachments default to `trueForgeAttachmentAdapter`.
</ParamField>

<ParamField path="onError" type="(error: unknown) => void">
  Called when the server fails to resolve or the runtime raises an error.
</ParamField>

## 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.

<Warning>
  If `window.location.search` contains `screenType=mcp-auth`, the component renders only the
  OAuth completion screen and no layout. See [MCP OAuth](/ui-sdk/setup-custom-ui/mcp-oauth).
</Warning>

## Example

```tsx theme={null}
<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)}
/>
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.