ilovetui/README.md

Ilovetui

A minimal Go library that provides a shared Base16 color theme for terminal UIs built with bubbletea and lipgloss, plus a small collection of Bubble Tea v2 components on top of it.

The idea is simple: instead of every TUI app managing its own colors, they all share one theme file so the user customizes once and every app looks consistent.

Packages

• github.com/anotherhadi/ilovetui/style — the theme itself: colors, pre-built panel styles, config loading.
• github.com/anotherhadi/ilovetui/bubbles — themed constructors for official bubbles/v2 components (help, textarea, textinput, list, table, filepicker, spinner, progress, paginator, viewport).
• github.com/anotherhadi/ilovetui/tabs, .../helpbar, .../modal, .../drawer, .../notification — custom components not found in the official bubbles library, styled from the same theme.

How it works

On import, style automatically loads the user's theme from ~/.config/ilovetui/config.yaml (respecting $XDG_CONFIG_HOME). If no config exists, it falls back to the embedded default. The active theme is exposed as the package-level variable S.

import "github.com/anotherhadi/ilovetui/style"

// Use colors directly
s := lipgloss.NewStyle().Foreground(style.S.Primary)

// Use pre-built panel styles
box := style.RenderWithTitle(style.S.PanelFocused, "Title", content, w, h)

No setup required — just import and use.

Installation

go get github.com/anotherhadi/ilovetui

Theme

The theme follows the Base16 standard (16 colors). The library exposes both the raw palette and semantic aliases:

Alias	Base16	Meaning
Background	Base00	Background
SubtleBg	Base01	Lighter Background / Status Bars
Selection	Base02	Selection Background
Subtle	Base03	Comments / Invisibles
Muted	Base04	Dark Foreground / Status Bars
Text	Base05	Default Foreground
Primary	Base0D	Functions / Methods / Headings / Accent
Success	Base0B	Strings / Success / Diff Inserted
Warning	Base09	Integers / Constants / Booleans
Error	Base08	Variables / Errors / Diff Deleted

The default theme is style/default.yaml. Copy it and edit to customize:

mkdir -p ~/.config/ilovetui
cp $(go env GOPATH)/pkg/mod/github.com/anotherhadi/ilovetui*/style/default.yaml ~/.config/ilovetui/config.yaml

Or let your app write it on first run:

style.WriteDefaultConfig(style.DefaultConfigPath())

Pre-built styles

S ships with a few ready-to-use lipgloss styles:

Field	Description
S.Bold	Bold text
S.Faint	Muted / dimmed text
S.Panel	Rounded border, unfocused (Subtle color)
S.PanelFocused	Rounded border, focused (Primary color)

Helpers

// Inner usable height of a bordered panel with outer height h
inner := style.ContentHeight(h)

// Render a box with a title embedded in the top border
box := style.RenderWithTitle(style.S.PanelFocused, "Header", content, w, h)

API

style.Init()                      // Reload from default config path
style.InitFrom(path string)       // Reload from a custom path
style.InitFromBytes(data []byte)  // Parse raw YAML
style.DefaultConfigPath() string  // ~/.config/ilovetui/config.yaml
style.WriteDefaultConfig(path)    // Write default config if missing

Themed official components

import "github.com/anotherhadi/ilovetui/bubbles"

h  := bubbles.NewHelp()
ta := bubbles.NewTextarea(false)
ti := bubbles.NewTextInput()
l  := bubbles.NewList(items, width, height)
t  := bubbles.NewTable()
fp := bubbles.NewFilePicker()
sp := bubbles.NewSpinner()
pr := bubbles.NewProgress()
pg := bubbles.NewPaginator()
vp := bubbles.NewViewport()

Each constructor mirrors the official component's own New, then applies style.S on top. Where the official New takes options (spinner, table, progress), they're forwarded before the theme is applied, so you can still customize behavior; anything you pass that also sets colors will be overridden by the theme afterward.

Custom components

import "github.com/anotherhadi/ilovetui/tabs"

t := tabs.New([]tabs.Item{{Title: "First", Model: firstPane}, {Title: "Second", Model: secondPane}})

tabs renders a horizontal tab bar styled from style.S. The host application renders the content below it; see tabs/README.md and examples/tabs for a full example.

For the other custom components, see their own README: helpbar (responsive help bar that reflows into as many columns as fit), modal (centered popup dialogs), drawer (left/right sidebar panels, mirroring modal) and notification (toast notifications).

Projects using ilovetui

• anotherhadi/spilltea: A minimal, terminal-based HTTP(S) proxy for pentesters and CTF players. Think Burp Suite or Caido, but entirely in your terminal.
• anotherhadi/usbguard-tui: A terminal UI for managing USB devices via usbguard. TUI built with golang & bubbletea.
• anotherhadi/jwt-tui: A terminal UI for inspecting, editing, and signing JSON Web Tokens (JWTs).