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

# Theme

> Theme provider, hooks, presets, brand, and slots.

## Components

| Export | Purpose |
| - | - |
| `ThemeProvider` | Owns light/dark/system state and injects token CSS variables on a wrapper `div.aui-theme-root`. |
| `SlotsProvider` | Slot override registry. Must sit outside `TrueForgeChatProvider`. |
| `BrandLogo` | Product mark. `variant="icon"` renders the compact square asset; `variant="logo"` renders the wider asset and falls back to the icon. With no brand override, the logo variant uses the built-in TrueForge wordmark. Overridable slot. Props: `{ className?, variant?: "icon" \| "logo" }`. |
| `Icon` | Renders a built-in icon by name, or your replacement when `theme.icons` maps that name. Props: `{ name: string \| readonly string[] } & IconProps`. An array resolves to its **last** element, accommodating Font Awesome-style `["far", "clone"]` tuples; it is not a fallback chain. An unresolved name renders nothing. |

## Hooks

| Hook | Returns |
| - | - |
| `useTheme()` | `{ preset, mode, preference, isDark, setTheme }`. `setTheme` is a no-op when `theme.mode` is controlled. |
| `useThemeMode()` | Resolved `"light" \| "dark"`. Reads the mode published by `SlotsProvider`, so it returns `"light"` when no `SlotsProvider` is above it — even in dark mode. |
| `useBrand()` | The active `BrandConfig`. |
| `useBrandName()` | The configured name; `undefined` for unnamed custom branding; or `"TrueForge"` when no custom image is configured. Safe outside a provider. |
| `resolveBrandChrome(brand)` | `{ expandedVariant, collapsedVariant, showTitle }` from `brand.mode`. Prefer this over re-deriving field combinations. |
| `useThemeIcons()` | The `IconMap` from `theme.icons`. |
| `useContentClassNames()` | `theme.classNames`; throws outside a provider. |
| `useOptionalContentClassNames()` | Same, but returns `{}` outside a provider instead of throwing — no null check needed. |
| `useSlot(name)` | The component currently registered for a slot. |

## Values

| Export | Description |
| - | - |
| `PRESETS` | `Record<ThemePreset, { light, dark }>` token maps — useful for building a preset picker. |
| `resolvePresetTokens(preset, mode)` | Resolved tokens for one preset and mode. |
| `defaultSlots` | The default component for every slot; read it to inspect what a slot renders by default. |

## Types

`ThemeConfig`, `ThemeMode`, `ThemePreset`, `SemanticTokens`, `BrandConfig`, `BrandMode`, `BrandImage`, `BrandLogoConfig`,
`BrandChrome`, `ContentClassNames`, `IconMap`, `ThemeIconProps`, `IconProps`, `LayoutProp`, `AtomSlots`,
`SlotOverrides`.

```ts theme={null}
type ThemePreset = "trueforge" | "claude" | "chatgpt" | "gemini";
type ThemeMode = "light" | "dark" | "system";
type SlotOverrides = Partial<AtomSlots>;
```

`AtomSlots` is derived from the SDK's default slot table, so it enumerates exactly the
overridable slots — your editor's autocomplete on `overrides` is authoritative. See
[Slot overrides](/ui-sdk/setup-custom-ui/slot-overrides).

Most token names map to a CSS variable of the same name; the exceptions are listed in
[Theming](/ui-sdk/setup-custom-ui/custom-theme).


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