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

> Learn how Superfile loads and applies custom themes from TOML files. Discover the fallback mechanism for missing themes with this complete guide to yorukot/superfile customization.

- Repository: [Yorukot/superfile](https://github.com/yorukot/superfile)
- Tags: how-to-guide
- Published: 2026-07-28

---

**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`](https://github.com/yorukot/superfile/blob/main/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`](https://github.com/yorukot/superfile/blob/main/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`](https://github.com/yorukot/superfile/blob/main/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`](https://github.com/yorukot/superfile/blob/main/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`](https://github.com/yorukot/superfile/blob/main/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:

```toml

# ~/.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:

```toml

# ~/.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:

```go
// 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`](https://github.com/yorukot/superfile/blob/main/src/config/fixed_variable.go).
- **Selection mechanism**: The `theme` key in [`config.toml`](https://github.com/yorukot/superfile/blob/main/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`](https://github.com/yorukot/superfile/blob/main/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`](https://github.com/yorukot/superfile/blob/main/src/config/fixed_variable.go).

### What happens if my custom theme file is missing?

If the theme file specified in [`config.toml`](https://github.com/yorukot/superfile/blob/main/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`](https://github.com/yorukot/superfile/blob/main/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`](https://github.com/yorukot/superfile/blob/main/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`](https://github.com/yorukot/superfile/blob/main/monokai.toml) file located in `src/superfile_config/theme/`.