Theme

Overview

interface.theme sets the deployment theme: the colors, shape, typography, shadows and motion that every user sees, in both light and dark mode. It takes either the name of a theme bundled with LibreChat or an inline theme definition.

interface:
  theme: clickhouse

When interface.theme is unset, LibreChat behaves as before: users see the default LibreChat theme, or whatever build-time colors or stored theme apply to them.

This page covers what an operator sets in librechat.yaml. The theme engine itself, including the full token list and how each token maps to Tailwind utilities, is documented in the theme README in the LibreChat repository.

How the theme is chosen

The client picks one theme, highest priority first:

1. High-contrast modes. A user who picks high-contrast-light or high-contrast-dark, or whose system setting resolves to high contrast, always gets the built-in accessible palette.
2. interface.theme from librechat.yaml.
3. REACT_APP_THEME_* build-time colors. See Theme Colors.
4. The user's stored theme in their browser.

The deployment theme sets colors, shape, fonts, shadows and motion, but not the mode: each user still chooses light, dark or system themselves.

The deployment theme is never written to the user's browser storage. If you remove interface.theme, users get their own stored theme back (or the REACT_APP_THEME_* colors, when the build sets them).

The theme is part of the pre-login configuration, so the login and registration pages already render with it.

Shared links

A shared link paints the theme of the tenant that owns the link, not the theme of the person viewing it. If the owning tenant sets no interface.theme, or its shared-link configuration fails to load, the shared page shows no deployment theme rather than falling back to the viewer's. Leaving the shared page restores the viewer's theme.

Bundled themes

A name that is not one of these is ignored: the server logs it and drops interface.theme (see Validation), and the app falls back to the next source in the list above.

ClickHouse theme

interface.theme: clickhouse changes both color and shape:

• Palette. Every color token is defined in both modes from Click UI's light and dark tokens, so nothing falls back to the LibreChat palette. A few values are moved along their Click UI ramps where the verbatim value missed WCAG AA contrast.
• Accent. Near-black #151515 in light mode and the ClickHouse yellow #faff69 in dark mode, used for the accent, submit button and focus ring.
• Radii. A tighter scale taken from Click UI's border.radii: controls and sm through lg at 0.25rem, surfaces and xl/2xl at 0.5rem, large surfaces and 3xl at 0.75rem.
• Shadows. Click UI's single elevation shadow on every raised surface, at 0.15 opacity in light mode and 0.6 in dark, with a hairline shadow for the xs and sm steps.
• Controls. Disabled controls use the fill style with their own disabled colors, the switch is a compact 2rem by 1rem, and table rows get a 1px rule.
• Scrims. Every dialog scrim is at 0.75 opacity.
• Fonts. The UI font stays Inter. Code uses Inconsolata, which LibreChat bundles, followed by the same system monospace fallbacks as the default theme. Headings and dialog titles ask for Basier Square first, which is not bundled, so they render in Inter unless the viewer has it installed.

Inline theme definition

Instead of a name, interface.theme can hold a theme definition. Anything you leave out falls back to LibreChat's defaults for that mode, so a definition only needs the values you want to change.

interface:
  theme:
    version: 1
    name: acme
    modes:
      light:
        colors:
          rgb-accent-primary: '29 78 216'
          rgb-accent-primary-hover: '30 64 175'
          rgb-ring-primary: '29 78 216'
          rgb-surface-submit: '29 78 216'
          rgb-surface-submit-hover: '30 64 175'
          rgb-link: '29 78 216'
        appearance:
          controlRadius: '0.375rem'
          radiusLg: '0.375rem'
          radiusXl: '0.5rem'
          shadowLg: '0 8px 16px -4px rgb(0 0 0 / 0.2)'
      dark:
        colors:
          rgb-accent-primary: '96 165 250'
          rgb-accent-primary-hover: '147 197 253'
          rgb-ring-primary: '96 165 250'
          rgb-surface-submit: '37 99 235'
          rgb-surface-submit-hover: '29 78 216'
          rgb-link: '96 165 250'
        appearance:
          controlRadius: '0.375rem'
          radiusLg: '0.375rem'
          radiusXl: '0.5rem'
          shadowLg: '0 8px 16px -4px rgb(0 0 0 / 0.5)'
    brands:
      provider-openai: '#10a37f'

Validation

The server checks interface.theme with the same rules the browser applies before painting it, when librechat.yaml is loaded and on every config reload.

An invalid theme is dropped as if interface.theme were unset. A wrong version, a missing name, a mode other than light or dark, a field the definition format does not have (at the top level, such as css, or inside a mode, anything other than colors, appearance and brands), an unknown brand token, or a value of the wrong kind for any token makes the theme unusable. LibreChat removes interface.theme, logs a warning with one line per problem, and loads the rest of the configuration as usual, so a theme mistake never stops the server. Users then get the next source in How the theme is chosen: the REACT_APP_THEME_* colors or their stored theme, or LibreChat's default theme when neither applies. The log calls this the default theme:

Ignoring interface.theme in /app/librechat.yaml; the default theme applies instead:
- interface.theme.modes.dark.colors.rgb-surface-primary: Invalid RGB value for rgb-surface-primary: 300 16 32

A bundled theme name that does not exist is handled the same way (Unknown bundled theme "<name>", expected one of: librechat, clickhouse).

The colors and appearance maps work differently from the fields around them.

An unknown token is ignored, and the rest of the theme applies. A key inside colors or appearance that this version of LibreChat does not know, whether a typo or a token added in a newer version, costs only itself. The server logs it and leaves unknown colors out of the theme it sends to the browser:

interface.theme in /app/librechat.yaml names tokens this version ignores:
- interface.theme.modes.light.colors.rgb-surfce-secondary: Unknown light color token ignored: rgb-surfce-secondary

An unknown token is still checked for shape: a color name must be a plain lowercase token (letters, digits and -) holding an R G B value, and an appearance name must be camelCase holding a plain value without ;, {, }, <, > or url(). Anything else is an error and the whole theme falls back. Check the server log after changing a theme, because a misspelled token is only reported there.

The browser applies the same rules to the theme it receives and logs [DeploymentTheme] Ignoring invalid interface.theme: ... if it still has to reject one, for example when an older cached client meets a newer server.

Colors

Colors use the same token names as the theme engine: rgb- followed by the token, such as rgb-surface-primary, rgb-text-primary, rgb-border-medium, rgb-accent-primary or rgb-status-error-subtle. The full list of 106 tokens is themeColorTokens in packages/data-provider/src/theme.ts, which the server and the browser both read, and each token is described in the IThemeRGB interface in packages/client/src/theme/types/index.ts.

Beyond the surface, text, border, status and syntax palettes, these roles let a theme restyle specific interaction states and components:

Each value is a bare R G B triplet with every channel from 0 to 255, for example '255 255 255'. Hex values and rgb(...) are rejected. Quote the value so YAML reads it as a string.

A few tokens follow a related token you did set when you leave them out, so a partial palette stays coherent. For example, rgb-text-muted follows rgb-text-tertiary, rgb-surface-composer-hover and rgb-surface-pressed follow rgb-surface-hover, rgb-focus-outline follows rgb-ring-primary, rgb-focus-control follows rgb-text-primary, rgb-border-control follows rgb-border-light, rgb-switch-thumb follows rgb-surface-primary, rgb-table-header-text follows rgb-text-secondary, and rgb-table-header-fill follows rgb-surface-dialog.

Appearance

Appearance values are set per mode, and a mode without them uses the defaults below. To change shape in both modes, repeat the values under light and dark, as in the example above.

The defaults reproduce LibreChat's look, so a theme that sets none of these keys changes no shape.

Accepted values:

• Radii, controlHeight, spacing and text sizes: 0, or a number in px, rem or em (such as 0.25rem), or a single calc() of two such lengths (such as calc(0.5rem - 2px)).
• switchWidth and switchHeight: a positive length in px or rem. Both must use the same unit (a side you leave out uses its rem default), the width must exceed the height so the knob can travel, and the height must clear the 4px track border (more than 4px, or at least 0.5rem).
• tableCellSpaceY and tableRowStroke: 0, or a length in px or rem.
• disabledStyle: dim or fill.
• Line heights: a unitless number (such as 1.5), a single calc() dividing two numbers (such as calc(1.25 / 0.875)), or a length.
• Scrim opacities: a number from 0 to 1.
• Font families: any non-empty font-family list without ;, { or }. The font must be available to the browser: LibreChat bundles Inter, Roboto Mono and Inconsolata, so any other family has to be installed on the viewer's machine or served by your deployment, or the next family in the list is used.
• Shadow steps (shadow2xs through shadow2xl): a concrete box-shadow list, or none. var(), env(), attr() and url() are rejected.
• elevationSurface: any non-empty box-shadow value without ;, {, } or url().
• Motion: a duration in ms or s, such as 120ms.

Brands

brands recolors the provider icons shown next to models. It can be set once at the top level for both modes, and overridden per mode under modes.<mode>.brands.

Values are hex colors (#rgb, #rrggbb or #rrggbbaa). The fills may also be a linear-gradient(...); provider-foreground, the icon glyph color, must be a hex color.

Using the theme outside LibreChat

The @librechat/client package publishes the theme as a stylesheet, so another app built on its components can paint the same tokens. Import @librechat/client/theme.css in the stylesheet that imports Tailwind:

@import 'tailwindcss';
@import '@librechat/client/theme.css';

It carries the semantic color tokens and their Tailwind mappings, the default value of every color and appearance token, and the @font-face rules for Inter, Roboto Mono and Inconsolata. The font files ship in the package as @librechat/client/fonts/*, so the app's bundler (Vite, webpack or esbuild) has to resolve and emit them; a setup that serves compiled CSS without a bundler has to serve those paths itself. A font is only downloaded when text renders in it.