How to Customize Border Styles and Characters in Superfile: A Complete Config Guide

To customize border styles and characters in superfile, edit the border_* fields in $HOME/.config/superfile/config.toml, which the application validates as single-runewidth glyphs and renders through lipgloss.Border on startup.

Superfile is a keyboard-driven terminal file manager written in Go that leverages the Bubble Tea ecosystem for its interface. If you want to customize border styles and characters in superfile, you can override the default panel glyphs—top, bottom, corners, and dividers—inside its TOML configuration without modifying any source code. The values are loaded into the global Config struct, enforced by rune-width validation, and passed to the lip-gloss renderer for every bordered panel.

Where Border Settings Are Defined in the Source Code

In src/internal/common/config_type.go (lines 101–145), the Config struct exposes dedicated fields for every visual border component. These map directly to keys you can set in $HOME/.config/superfile/config.toml:

• border_top — Horizontal line at the top edge. Maps to Config.BorderTop as referenced in src/internal/ui/spf_renderers.go (line 136).
• border_bottom — Horizontal line at the bottom edge. Maps to Config.BorderBottom (line 137).
• border_left — Vertical line on the left edge. Maps to Config.BorderLeft (line 138).
• border_right — Vertical line on the right edge. Maps to Config.BorderRight (line 139).
• border_top_left — Upper-left corner glyph. Maps to Config.BorderTopLeft (line 140).
• border_top_right — Upper-right corner glyph. Maps to Config.BorderTopRight (line 141).
• border_bottom_left — Lower-left corner glyph. Maps to Config.BorderBottomLeft (line 142).
• border_bottom_right — Lower-right corner glyph. Maps to Config.BorderBottomRight (line 143).
• border_middle_left — Divider glyph on the left side of internal splits. Maps to Config.BorderMiddleLeft (line 144).
• border_middle_right — Divider glyph on the right side of internal splits. Maps to Config.BorderMiddleRight (line 145).

How Superfile Validates Border Characters

When superfile launches, src/internal/common/load_config.go (lines 90–116) parses your TOML file and enforces a strict layout rule. Every configured border character must have a width of exactly one rune. If a glyph is wider or empty, the UI layout engine would miscalculate panel dimensions, so the loader rejects invalid values before they reach the renderer.

How the UI Renderer Applies Custom Borders

The drawing logic lives in src/internal/ui/spf_renderers.go. The function DefaultLipglossBorder() (lines 134–145) assembles a lipgloss.Border value from the current Config fields. Additional styling logic in src/internal/ui/rendering/border.go (lines 56–122) then applies that border object to individual UI components such as the file list, sidebar, modals, and footer.

Before attaching any border, the renderer checks cfg.BorderRequired (lines 16–18). If this boolean is false, it skips border generation entirely and draws panels with no surrounding characters.

Practical Configuration Examples

Classic Box-Drawing Characters

Below is a complete TOML snippet that replaces the default borders with classic box-drawing glyphs. Add these lines to $HOME/.config/superfile/config.toml, then restart superfile (or reload the config with :reload inside the app) for the changes to take effect.

# $HOME/.config/superfile/config.toml

border_top = "─"
border_bottom = "─"
border_left = "│"
border_right = "│"
border_top_left = "╔"
border_top_right = "╗"
border_bottom_left = "╚"
border_bottom_right = "╝"
border_middle_left = "┣"
border_middle_right = "┫"

Unicode Emoji Glyphs

Because superfile validates rune width rather than byte length, you can use emoji glyphs as long as each one occupies a single terminal cell. Save the following to your configuration file and relaunch the application.

border_top = "━"
border_bottom = "━"
border_left = "┃"
border_right = "┃"
border_top_left = "🟢"
border_top_right = "🟢"
border_bottom_left = "🔴"
border_bottom_right = "🔴"
border_middle_left = "🟡"
border_middle_right = "🟡"

Disable All Borders

If you prefer a minimal, borderless interface, set the border_required field to false. When cfg.BorderRequired is disabled in spf_renderers.go (lines 16–18), the renderer omits border characters entirely.

border_required = false   # disables all borders

Summary

• Superfile stores border glyphs in src/internal/common/config_type.go as Config.BorderTop, Config.BorderBottom, and related fields.
• The loader in src/internal/common/load_config.go (lines 90–116) validates that every border character is exactly one rune wide.
• src/internal/ui/spf_renderers.go constructs a lipgloss.Border via DefaultLipglossBorder() (lines 134–145) and respects the border_required toggle (lines 16–18).
• You override values in $HOME/.config/superfile/config.toml using snake_case keys such as border_top, border_left, and border_middle_left.
• Additional border-application logic in src/internal/ui/rendering/border.go (lines 56–122) handles per-component rendering.
• Set border_required = false to remove borders globally without blanking individual character fields.

Frequently Asked Questions

Where is the superfile configuration file located?

The default path is $HOME/.config/superfile/config.toml on Linux and macOS. Superfile reads this TOML file at startup, so any changes to border characters require a restart of the application to take effect.

What happens if a border character is wider than one rune?

src/internal/common/load_config.go enforces a single-rune width check (lines 90–116). A character that is too wide would break lip-gloss layout calculations, so the validator prevents malformed glyphs from reaching the renderer.

Can I use emoji characters for panel borders?

Yes. As shown in the configuration examples, emoji glyphs are valid provided each one reports a width of exactly one rune. Superfile does not restrict the visual style, only the rune width, so colored emoji corners and dividers render correctly in supported terminals.

How do I disable all borders without editing each glyph?

Set border_required = false in config.toml. The renderer checks cfg.BorderRequired in src/internal/ui/spf_renderers.go (lines 16–18) and skips border generation entirely, producing a flat, borderless UI.

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