Custom Themes Guide

Surge features a powerful palette-based theme engine that allows you to customize every aspect of the TUI’s appearance using simple .toml files.

Theme Resolution

Surge looks for themes in the following order:

1. Direct Path / Working Directory: If you provide a full path or a filename in your current directory (including autocomplete results).
2. Local themes/ Folder: Surge looks for themes in a themes/ directory relative to where it is running (useful for bundled themes).
3. Global Surge Themes: Surge then checks for themes in your user configuration directory:
   • Linux: ~/.config/surge/themes/
   • macOS: ~/Library/Application Support/surge/themes/
   • Windows: %APPDATA%\surge\themes\

Theme File Format

A Surge theme is a TOML file containing a [colors] table. The system uses a 16-color palette (Normal + Bright) plus primary background and foreground colors.

Basic Structure

[colors]
name = "My Custom Theme"

[colors.primary]
background = "#1a1b26"
foreground = "#a9b1d6"

[colors.normal]
black   = "#32344a"
red     = "#f7768e"
green   = "#9ece6a"
yellow  = "#e0af68"
blue    = "#7aa2f7"
magenta = "#ad8ee6"
cyan    = "#449dab"
white   = "#787c99"

[colors.bright]
black   = "#444b6a"
red     = "#ff7a93"
green   = "#b9f27c"
yellow  = "#ff9e64"
blue    = "#7da6ff"
magenta = "#bb9af7"
cyan    = "#0db9d7"
white   = "#acb0d0"

Mapping Details

Surge maps these terminal colors to specific UI elements:

Color Group	Color	Surge UI Mapping
Normal	black	Selection backgrounds, Borders, Secondary text
	red	Error states
	green	Active download state
	yellow	Paused state
	blue	Version info, Action hints
	magenta	Completed state
	cyan	Setting labels, Links
	white	Standard text
Bright	black	Secondary info, Timestamps
	red	Progress bar start (Gradient)
	magenta	Progress bar end (Gradient)

---

Adaptive Themes

You can bundle both Dark and Light variants into a single theme file. Surge will automatically switch between them based on your theme setting (Adaptive/Light/Dark).

[colors]
name = "My Adaptive Theme"

# Default colors used if mode-specific ones are missing
[colors.primary]
background = "#000000"
foreground = "#ffffff"

[colors.dark]
[colors.dark.primary]
background = "#1a1b26"
# ... other dark colors

[colors.light]
[colors.light.primary]
background = "#ffffff"
# ... other light colors

Applying a Theme

1. Place your .toml file in the themes directory.
2. Open Surge TUI.
3. Go to Settings (s).
4. Navigate to Theme File (theme_path).
5. Type the name of your theme (without .toml) or press Tab to browse and select it.