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

> Customize Superfile border styles and characters by editing config.toml. Learn how to tailor your terminal UI with lipgloss.Border on startup.

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

---

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

```toml

# $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.

```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 = "🟡"

```

### 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`](https://github.com/yorukot/superfile/blob/main/spf_renderers.go) (lines 16–18), the renderer omits border characters entirely.

```toml
border_required = false   # disables all borders

```

## Summary

- Superfile stores border glyphs in [`src/internal/common/config_type.go`](https://github.com/yorukot/superfile/blob/main/src/internal/common/config_type.go) as `Config.BorderTop`, `Config.BorderBottom`, and related fields.
- The loader in [`src/internal/common/load_config.go`](https://github.com/yorukot/superfile/blob/main/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`](https://github.com/yorukot/superfile/blob/main/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`](https://github.com/yorukot/superfile/blob/main/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`](https://github.com/yorukot/superfile/blob/main/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`](https://github.com/yorukot/superfile/blob/main/config.toml). The renderer checks `cfg.BorderRequired` in [`src/internal/ui/spf_renderers.go`](https://github.com/yorukot/superfile/blob/main/src/internal/ui/spf_renderers.go) (lines 16–18) and skips border generation entirely, producing a flat, borderless UI.