Updated May 2026Edit this page ↗

Built-in Themes

@termuijs/tss ships six built-in themes and a runtime theme switcher. All themes use the same CSS variable names so widgets styled against var(--primary) work with every theme.

Available themes

NameCharacterPrimary Color
defaultDark background, cyan/green accents, clean terminal aestheticcyan
cyberpunkNeon magenta and cyan on deep navy, high contrast#ff00ff
nordArctic blues and muted grays, easy on the eyes#88c0d0
draculaDeep purple background with pastel pink, green, and yellow accents#bd93f9
catppuccinWarm pastels on dark, soft and legible#cba6f7
solarizedEthan Schoonover's classic — yellow, orange, blue on warm base#268bd2

Loading a built-in theme

○TYPESCRIPT
import { ThemeEngine, BUILTIN_THEMES } from '@termuijs/tss'
 
const engine = new ThemeEngine()
engine.load(BUILTIN_THEMES['dracula'])
engine.setTheme('dracula')

BUILTIN_THEMES is a Record<string, string> mapping theme names to TSS strings. You can load multiple at once:

○TYPESCRIPT
// Load all built-ins at once
import { getAllBuiltinThemes } from '@termuijs/tss'
engine.load(getAllBuiltinThemes())

useTheme hook

useTheme gives JSX components access to the active theme and the ability to switch:

○TYPESCRIPT
import { useTheme } from '@termuijs/tss'
 
function ThemeSelector() {
    const { theme, setTheme, availableThemes } = useTheme()
 
    return (
        <col>
            <Text>Active: {theme}</Text>
            {availableThemes.map((name) => (
                <Text key={name} bold={name === theme} onClick={() => setTheme(name)}>
                    {name}
                </Text>
            ))}
        </col>
    )
}

Return value

PropertyTypeDescription
themestringName of the active theme
setTheme(name: string) => voidSwitch themes at runtime
availableThemesstring[]All loaded theme names

AutoThemeProvider

AutoThemeProvider detects the terminal's background color via an OSC escape query and picks the closest built-in theme automatically. Useful when you don't want to force a specific theme on users with custom terminal colors.

○TYPESCRIPT
import { AutoThemeProvider } from '@termuijs/tss'
 
function Root() {
    return (
        <AutoThemeProvider fallback="dracula">
            <App />
        </AutoThemeProvider>
    )
}

Props

PropTypeDefaultDescription
fallbackstring'default'Theme to use if detection fails
engineThemeEngineAuto-createdProvide an existing engine if you've already loaded custom themes

The provider wraps all descendant components in a ThemeContext, so useTheme() works anywhere below it.

Defining a custom theme

Write a TSS string with your own @theme block:

○TYPESCRIPT
const mytheme = `
@theme midnight {
  --primary: #a78bfa;
  --bg: #0f0f1a;
  --surface: #1a1a2e;
  --text: #e2e8f0;
  --text-muted: #64748b;
  --border: single;
  --border-color: #334155;
  --border-focus: #a78bfa;
  --error: #f87171;
  --success: #34d399;
  --warning: #fbbf24;
}
`
 
engine.loadAll([getAllBuiltinThemes(), mytheme])
engine.setTheme('midnight')

CSS variable reference

All built-in themes define these variables. Widgets use them via var(--name):

VariablePurpose
--primaryMain accent color — borders, highlights, active states
--secondarySecondary accent
--bgApplication background
--surfacePanel and card backgrounds
--textPrimary text color
--text-mutedDimmed text, placeholders, hints
--borderBorder style (single, double, round)
--border-colorInactive border color
--border-focusBorder color when focused
--errorError state
--successSuccess state
--warningWarning state

See also

  • TSS Overview — selector syntax, pseudo-classes, engine API
  • Theme Tokens — programmatic token objects and the tokensToTSS bridge
← PreviousOverviewNext →Theme Tokens