How Custom Themes Are Loaded and Applied in Superfile: Complete Guide

Superfile loads custom themes from TOML files located in its dedicated theme directory, automatically falling back to embedded default styles when a specified theme is missing.

The yorukot/superfile terminal file manager implements a flexible theming system that separates visual styling from application logic. Understanding how custom themes loaded and applied in superfile work enables you to create personalized color schemes by editing simple configuration files. This guide explains the complete data flow from disk to UI using the actual source implementation.

Theme Directory Structure and Configuration

Superfile organizes themes using a predictable file system hierarchy anchored by the SuperFileMainDir constant.

In src/config/fixed_variable.go, the application constructs the ThemeFolder path by appending /theme to the main configuration directory. This directory serves as the library for all available color schemes.

Your active theme is controlled through the theme key in src/superfile_config/config.toml. When the application initializes, it reads Config.Theme and constructs the full file path by joining ThemeFolder with the theme name and appending the .toml extension【load_config.go L192】.

The Theme Loading Workflow

The initialization sequence in src/internal/common/load_config.go handles file resolution, validation, and parsing through several distinct steps.

Locating the Theme File

During startup, Superfile resolves the absolute path to your selected theme by combining the ThemeFolder constant with your configured theme name. The system expects a valid TOML file at this location to proceed with custom styling【load_config.go L192】.

Fallback to Default Theme

If the specified theme file does not exist on disk, Superfile marshals the DefaultThemeString constant embedded in the binary. This ensures the interface remains functional even with missing or corrupted theme files, guaranteeing a consistent user experience【load_config.go L195】.

Directory Initialization

Before attempting to read any theme data, the code verifies that ThemeFolder exists using os.MkdirAll. This preemptive check prevents file system errors and ensures the theme directory is ready for reading or writing operations【load_config.go L284‑L287】.

Bootstrapping Default Themes

When Superfile creates the theme folder for the first time, it automatically copies monokai.toml into the directory. This provides users with a working reference template that demonstrates the expected TOML structure and valid color field names【load_config.go L310‑L311】.

Parsing and Application

The selected theme TOML is unmarshaled into the Theme struct defined in src/internal/common/config_type.go using the go-toml library. This struct contains fields for all UI elements including FilePanelBG, SidebarBG, FooterBG, Cursor, and ModalBG【load_config.go L217‑L218】.

Once parsed, these values flow directly into the Bubble Tea rendering pipeline. UI components reference the populated Theme struct to style borders, backgrounds, and text colors dynamically.

Creating and Applying a Custom Theme

To implement a custom theme, create a new TOML file in the theme directory and reference it in your configuration.

First, create your theme definition:

# ~/.config/superfile/theme/my-dark.toml

file_panel_bg = "#1e1e2e"
sidebar_bg = "#282a36"
footer_bg = "#1e1e2e"
cursor = "#ff79c6"
code_syntax_highlight = "dracula"
border = "#bd93f9"

Then activate it in your main configuration:

# ~/.config/superfile/config.toml

theme = "my-dark"

Restart Superfile to see your custom colors applied immediately.

Runtime Configuration Reload

Superfile supports hot-reloading configuration values without a full restart. Trigger a reload programmatically using the internal configuration loader:

// Refresh configuration and theme at runtime
if err := internal.LoadConfig(); err != nil {
    log.Fatalf("failed to reload config: %v", err)
}

Summary

• Theme location: Files reside in the ThemeFolder directory (located at SuperFileMainDir/theme) as defined in src/config/fixed_variable.go.
• Selection mechanism: The theme key in config.toml determines which .toml file Superfile attempts to load.
• Robust fallback: Missing theme files trigger automatic fallback to DefaultThemeString, ensuring the UI never breaks.
• Auto-initialization: Superfile automatically creates the theme directory and seeds it with monokai.toml on first run.
• Data flow: The go-toml library unmarshals theme files into the Theme struct, which Bubble Tea components consume for rendering.

Frequently Asked Questions

Where does Superfile store theme files?

Superfile stores themes in the directory defined by the ThemeFolder constant, which resolves to <SuperFileMainDir>/theme/. On most Linux systems, this maps to ~/.config/superfile/theme/, though the exact location depends on your operating system's configuration standards as implemented in src/config/fixed_variable.go.

What happens if my custom theme file is missing?

If the theme file specified in config.toml does not exist, Superfile automatically falls back to the embedded DefaultThemeString constant. This failsafe mechanism, implemented in src/internal/common/load_config.go, ensures the application remains usable even when theme files are accidentally deleted or renamed.

Can I reload themes without restarting Superfile?

Yes, Superfile supports reloading configuration and themes at runtime by calling internal.LoadConfig(). This function re-reads the theme file path specified in your configuration and unmarshals the TOML data into the active Theme struct, applying new colors immediately without requiring a process restart.

What format should theme files use?

Theme files must use TOML format with fields matching the Theme struct defined in src/internal/common/config_type.go. Required fields include color hex codes for file_panel_bg, sidebar_bg, cursor, and border, along with the code_syntax_highlight string. You can copy the structure from the default monokai.toml file located in src/superfile_config/theme/.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}