Layout, Theming & Branding

Preset Layouts

The sidebar view is the default layout. You can customize the layout by passing one of the predefined options: sidebar, drawer, dock, or widget.

sidebar(default)
drawer
dock
widget

A full-page chat experience with persistent conversation history in a left sidebar. The default choice for a dedicated chat surface.

<TrueForgeUI server={server} layout="sidebar" />

Sidebar layout — a persistent thread list on the left beside a full-page chat — Sidebar: full-page chat with the thread list pinned on the left.

Chat history is tucked into an overlay drawer and can be opened using the history icon. Ideal for smaller viewports, such as tablets and compact monitors, where screen space is limited.

<TrueForgeUI server={server} layout="drawer" />

Drawer layout — the thread list collapsed into an overlay drawer — Drawer: the thread list collapses into an overlay for narrow viewports.

A chat panel pinned to the right edge, using the available space up to a maximum width of 400px.

<TrueForgeUI server={server} layout="dock" />

Dock layout — a compact chat panel pinned to the right edge of the app — Dock: a compact panel pinned to the right edge, up to a 400px cap.

Built-in layouts are code-split, so only the layout you use is loaded into your bundle. The other three layouts are excluded, keeping your bundle size smaller. A lightweight placeholder is displayed while the selected layout loads.

Preset Themes

Choose from four built-in themes - Claude, ChatGPT, Gemini, and TrueForge, or create a custom theme to match your brand.

The theme object

type BrandImage = string | { src?: string; light?: string; dark?: string };

type BrandMode = "icon-title" | "icon-only" | "logo";

type BrandConfig =
  | { mode: "icon-title"; name: string; icon?: BrandImage; logo?: never; href?: string }
  | { mode: "icon-only"; name: string; icon: BrandImage; logo?: never; href?: string }
  | { mode: "logo"; name: string; icon: BrandImage; logo: BrandImage; href?: string };

type ThemeConfig = {
  preset?: "trueforge" | "claude" | "chatgpt" | "gemini"; // default "trueforge"
  mode?: "light" | "dark" | "system";
  brand?: BrandConfig;
  ...
};

Set brand.mode, then pass the fields that mode requires. name always labels the mark.

Look	`mode`	Required	Expanded	Collapsed
Default	omit `brand`	—	TrueForge wordmark	TrueForge square
Icon + title	`"icon-title"`	`name` (+ optional `icon`)	square + title	square
Icon only	`"icon-only"`	`name`, `icon`	square	square
Wide logo	`"logo"`	`name`, `icon`, `logo`	wide logo	square

App.tsx

<TrueForgeUI
  ...
  theme={{
    preset: "trueforge",
    mode: "system",
    brand: {
      mode: "logo",
      name: "Acme",
      icon: "/icon.svg",
      logo: "/wordmark.svg",
    }
  }}
/>

icon is the square asset used in collapsed and compact surfaces. logo is the wider asset used when mode is "logo" and requires icon as its compact fallback. When brand is omitted, expanded chrome uses the built-in TrueForge wordmark and compact surfaces use the built-in square mark. The chatgpt, claude, and gemini themes are shown below:

TrueForge UI with the chatgpt theme preset — chatgpt

TrueForge UI with the claude theme preset — claude

TrueForge UI with the gemini theme preset — gemini

Light and dark mode

If you omit this key, the SDK defaults to the system theme, and users can switch between light and dark mode through the UI. If you want the SDK theme to follow your application’s theme, set this value to light, dark, or system. This allows the SDK to stay in sync with the main application theme. When the theme is explicitly set, the user cannot change it through the UI.

The TrueForge UI SDK rendered in dark mode — Dark mode applied to the chat UI.

Separate logo for light and dark theme

You can also provide separate logos for light and dark modes, allowing your branding to remain visible and optimized for each theme, as shown below:

App.tsx

<TrueForgeUI
  ...
  theme={{
    ...
    brand: {
      mode: "logo",
      name: "Acme",
      icon: {
        light: "/icon/light.svg",
        dark: "/icon/dark.svg",
      },
      logo: {
        light: "/wordmark/light.svg",
        dark: "/wordmark/dark.svg",
      },
      href: "https://example.com",
    }
  }}
/>

The icon and logo sources are selected based on the resolved theme mode. When mode is omitted, they automatically follow the system theme.

Provide both light and dark to use a different image for each mode.
Provide only one of light or dark to use the same image in both modes.
Use src for a mode-independent image.
Set brand.mode first (icon-title | icon-only | logo); name is required and always labels images.
Visible title text only appears for mode: "icon-title".
Set the brand-level href to make configured images clickable.

For more advanced use cases, such as rendering an inline SVG or an animated logo, override the BrandLogo slot instead of passing a React node through the theme object.

App.tsx

import logoUrl from "./logo.svg";

function MyCustomLogo() {
  return <img src={logoUrl} alt="My custom logo" />;
}

<TrueForgeUI
  ...
  overrides={{ BrandLogo: MyCustomLogo }}
/>

Getting Started

TrueForge Harness

SDK

UI Chat

Project

Layout, Theming & Branding

Preset Layouts

Preset Themes

The theme object

Light and dark mode

Separate logo for light and dark theme

​Preset Layouts

​Preset Themes

​The theme object

​Light and dark mode

​Separate logo for light and dark theme

Preset Layouts

Preset Themes

The theme object

Light and dark mode

Separate logo for light and dark theme