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. Values are Click UI's own, even where a pairing falls below WCAG AA contrast. Users who need more contrast can pick a high-contrast mode, which always uses the built-in accessible palette (see How the theme is chosen).
• Accent. Near-black #151515 in light mode and the ClickHouse yellow #faff69 in dark mode, used for the accent and submit button. The focus ring is Click UI's outline color: blue #437eef in light mode, #faff69 in dark.
• Buttons. The primary button is #302e32 in light mode and #faff69 in dark, with Click UI's hover steps.
• Radii. A tighter scale taken from Click UI's border.radii: controls, menus, popovers, tooltips, tabs, the composer's action buttons and sm through lg at 0.25rem, surfaces and xl/2xl at 0.5rem, large surfaces and 3xl at 0.75rem.
• Borders. Decorative outlines on controls and chips and the hairlines inside stroked surfaces are hidden (chromeBorderAlpha and insetBorderAlpha at 0), so surfaces are separated by fill; field edges and the neutral button's border stay. Destructive actions use the soft style.
• Shadows. Click UI's single elevation shadow on every raised surface, menus and dragged items, at 0.15 opacity in light mode and 0.6 in dark, with a hairline shadow for the 2xs through sm steps. Tooltips have no shadow.
• Controls. Buttons and fields are 2rem tall, including the sign-in field and submit button (this theme sets authFieldHeight and authButtonHeight to 2rem, where the defaults are 2.75rem and 3rem), controls are padded 1rem with a 0.5rem icon gap and a regular (400) label weight. Fields are filled (fieldFillStyle: fill) and swap their edge color on focus (fieldFocusStyle: border); labels are 0.75rem at weight 500. 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.
• Dialogs. A 1px edge, 2rem side padding, and titles at 1.25rem, weight 700, in the Inter stack. Every dialog scrim is at 0.75 opacity.
• Fonts. The UI font stays Inter. Code uses Click UI's mono stack, "Inconsolata", Consolas, "SFMono Regular", monospace; LibreChat bundles Inconsolata. Headings 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).

A theme set through a config override (for a role, group or user in the Admin Panel) follows the same rules, with one difference: an invalid override theme falls back to the base interface.theme from librechat.yaml, not to the default theme. Those log lines start with [getAppConfig], for example [getAppConfig] Ignoring interface.theme from a config override; the base theme applies instead:.

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 169 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. The defaults are the same in both modes except menuShadow and tooltipShadow, which are heavier in dark mode, and buttonNeutralBorderOpacity, which is opaque in dark mode. 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, controlPaddingX, buttonPaddingX, controlGap, buttonHeight, buttonHeightSm, fieldHeight, fieldPaddingY, spacing, tooltip padding and text size, text and label sizes, and the dialog lengths (dialogStroke, dialogPaddingX, dialogHeaderGap, dialogTitleSize): 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)).
• buttonHeightXs, buttonHeightLg, buttonHeightCompact, iconButtonSizeSm, fieldHeightLg, authFieldHeight, authButtonHeight and authActionHeight: a length in px or rem of at least 24px (1.5rem), the minimum pointer target size.
• iconSize: 12px to 20px (0.75rem to 1.25rem). iconSizeMd: 20px to 24px. iconSizeLg: 16px to 32px. checkboxSize: 16px to 24px. listMaxHeight: 128px to 640px (8rem to 40rem). Each is a length in px or rem.
• tabMinWidth and listMinWidth: 0, or a length in px or rem.
• 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.
• focusRingWidth: a positive length in px or rem, so the focus indicator never disappears.
• focusRingOffset: 0, or a length in px or rem that may be negative (drawing the outline inside the element's edge).
• disabledStyle: dim or fill.
• fieldFocusStyle: ring or border.
• fieldFillStyle: transparent or fill.
• checkboxFillStyle: transparent or fill.
• Font weights (controlFontWeight, dialogTitleFontWeight, inlineCodeWeight): a whole number from 1 to 1000. labelFontWeight also accepts inherit.
• Line heights (the leading* steps, labelLeading and dialogTitleLeading): 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, buttonNeutralBorderOpacity, chromeBorderAlpha and insetBorderAlpha: a number from 0 to 1.
• destructiveStyle: fill or soft.
• 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), menuShadow, tooltipShadow and elevationDrag: 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.

Every appearance value must be a string. Quote numbers such as font weights, line heights and opacities ('500', '1.5', '0.8'); an unquoted YAML number is rejected.

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.