TUI Component Design Patterns
Best practices for building maintainable, testable TUI components using Bubbletea v2 and the Charm ecosystem, based on the hive diff viewer implementation.
Component Organization
Single Responsibility Per File
Each component should be in its own file with clear boundaries:
internal/tui/diff/
├── model.go # Top-level compositor that orchestrates sub-components
├── diffviewer.go # Diff content display with scrolling and selection
├── filetree.go # File navigation tree with expand/collapse
├── lineparse.go # Pure function utilities for parsing diff lines
├── delta.go # External tool integration (syntax highlighting)
└── utils.go # Shared utilitiesKey principle: Each file should represent ONE component with its own Model, Update, and View methods.
Component Hierarchy Pattern
For complex UIs, use a compositor pattern:
// Top-level Model composes sub-components
type Model struct {
fileTree FileTreeModel // Left panel
diffViewer DiffViewerModel // Right panel
focused FocusedPanel // Which component has focus
helpDialog *components.HelpDialog // Modal overlay
showHelp bool // Dialog visibility state
}
// Update delegates to focused component
func (m Model) Update(msg tea.Msg) (Model, tea.Cmd) {
switch m.focused {
case FocusFileTree:
m.fileTree, cmd = m.fileTree.Update(msg)
case FocusDiffViewer:
m.diffViewer, cmd = m.diffViewer.Update(msg)
}
return m, cmd
}Benefits:
- Each sub-component is independently testable
- Clear ownership of state and behavior
- Easy to reason about message flow
Component Structure
Standard Component Template
// 1. Model struct with all state
type ComponentModel struct {
// Data
items []Item
// UI State
selected int
offset int
width int
height int
// Feature flags
iconStyle IconStyle
expanded bool
}
// 2. Constructor with dependencies
func NewComponent(data []Item, cfg *config.Config) ComponentModel {
return ComponentModel{
items: data,
selected: 0,
iconStyle: determineIconStyle(cfg),
}
}
// 3. Update handles messages
func (m ComponentModel) Update(msg tea.Msg) (ComponentModel, tea.Cmd) {
switch msg := msg.(type) {
case tea.KeyPressMsg:
return m.handleKeyPress(msg)
case tea.WindowSizeMsg:
m.width = msg.Width
m.height = msg.Height
}
return m, nil
}
// 4. View renders output
func (m ComponentModel) View() string {
return m.render()
}
// 5. Helper methods for complex logic
func (m ComponentModel) render() string {
// Rendering logic here
}State Management
Avoid Hidden State
Bad:
// State hidden in closures or package variables
var currentSelection int
func (m Model) Update(msg tea.Msg) (Model, tea.Cmd) {
currentSelection++ // Modifying hidden state
}Good:
// All state explicit in model
type Model struct {
currentSelection int
}
func (m Model) Update(msg tea.Msg) (Model, tea.Cmd) {
m.currentSelection++ // Clear, traceable state change
return m, nil
}Separate UI State from Data
type DiffViewerModel struct {
// Immutable data
file *gitdiff.File
content string
lines []string
// Mutable UI state
offset int // Scroll position
cursorLine int // Current line
selectionMode bool // Visual mode active
selectionStart int // Selection anchor
}Benefits:
- Easy to test rendering at different scroll positions
- Data can be shared/cached without UI state interference
- Clear separation of concerns
Async Operations and Caching
Pattern: Command-Based Async with Caching
For expensive operations like syntax highlighting or external tool calls:
type ComponentModel struct {
cache map[string]*CachedResult
loading bool
}
// 1. Initiate async operation, return immediately
func (m *ComponentModel) SetData(data *Data) tea.Cmd {
filePath := data.Path
// Check cache first
if cached, ok := m.cache[filePath]; ok {
m.content = cached.content
m.lines = cached.lines
return nil
}
// Mark as loading, start async
m.loading = true
return func() tea.Msg {
content, lines := generateContent(data)
return contentGeneratedMsg{filePath, content, lines}
}
}
// 2. Handle completion message
func (m ComponentModel) Update(msg tea.Msg) (ComponentModel, tea.Cmd) {
switch msg := msg.(type) {
case contentGeneratedMsg:
// Cache result
m.cache[msg.filePath] = &CachedResult{
content: msg.content,
lines: msg.lines,
}
// Update display
m.content = msg.content
m.lines = msg.lines
m.loading = false
}
return m, nil
}Key points:
- Never block the UI thread
- Cache expensive computations
- Show loading state while processing
- Custom messages for async results
External Tool Integration
For tools like delta (syntax highlighting):
// 1. Check availability once at init
func NewDiffViewer(file *gitdiff.File) DiffViewerModel {
deltaAvailable := CheckDeltaAvailable() == nil
return DiffViewerModel{
deltaAvailable: deltaAvailable,
}
}
// 2. Separate pure function for testability
func generateDiffContent(file *gitdiff.File, deltaAvailable bool) (string, []string) {
diff := buildUnifiedDiff(file)
if !deltaAvailable {
return diff, strings.Split(diff, "\n")
}
// Apply syntax highlighting
return applyDelta(diff)
}
// 3. Make it async with proper error handling
func (m *ComponentModel) loadContent(file *gitdiff.File) tea.Cmd {
return func() tea.Msg {
content, lines := generateDiffContent(file, m.deltaAvailable)
return contentReadyMsg{content, lines}
}
}Visual Modes and Complex Interactions
Mode-Based Keybindings
For vim-style interfaces with normal/visual modes:
type Model struct {
mode Mode // Normal, Visual, Insert
selectionMode bool // Visual mode active
}
func (m Model) Update(msg tea.Msg) (Model, tea.Cmd) {
switch msg := msg.(type) {
case tea.KeyPressMsg:
// Handle mode transitions first
if msg.Code == 'v' && !m.selectionMode {
m.selectionMode = true
m.selectionStart = m.cursorLine
return m, nil
}
if msg.Code == tea.KeyEscape && m.selectionMode {
m.selectionMode = false
return m, nil
}
// Handle mode-specific behavior
if m.selectionMode {
return m.handleVisualMode(msg)
}
return m.handleNormalMode(msg)
}
return m, nil
}Selection State Management
For visual selection (highlighting lines):
type Model struct {
selectionMode bool
selectionStart int // Anchor point
cursorLine int // Active end
}
// Helper to get normalized selection range
func (m Model) SelectionRange() (start, end int, active bool) {
if !m.selectionMode {
return 0, 0, false
}
start = m.selectionStart
end = m.cursorLine
if start > end {
start, end = end, start
}
return start, end, true
}
// Use in rendering
func (m Model) View() string {
start, end, active := m.SelectionRange()
for i, line := range m.lines {
if active && i >= start && i <= end {
line = highlightStyle.Render(line)
}
// ... render line
}
}Scroll Management
Viewport Pattern
For scrollable content with fixed dimensions:
type Model struct {
lines []string
offset int // Top visible line
height int // Viewport height
}
// Calculate visible range
func (m Model) visibleLines() []string {
start := m.offset
end := min(m.offset + m.contentHeight(), len(m.lines))
return m.lines[start:end]
}
// Content height (excluding fixed UI elements)
func (m Model) contentHeight() int {
return m.height - headerHeight - footerHeight
}
// Scroll with cursor tracking
func (m Model) scrollDown() Model {
// Move cursor first
if m.cursorLine < len(m.lines)-1 {
m.cursorLine++
}
// Adjust viewport if cursor moved out of view
visibleBottom := m.offset + m.contentHeight() - 1
if m.cursorLine > visibleBottom {
m.offset++
}
return m
}Key principle: Cursor moves first, viewport follows to keep cursor visible.
Editor Integration
Opening External Editors
Pattern for jumping to specific line in editor:
func (m Model) openInEditor(filePath string, lineNum int) tea.Cmd {
return func() tea.Msg {
editor := os.Getenv("EDITOR")
if editor == "" {
editor = "vim"
}
// Format: editor +line file
arg := fmt.Sprintf("+%d", lineNum)
cmd := exec.Command(editor, arg, filePath)
// Important: Connect to terminal for interactive editors
cmd.Stdin = os.Stdin
cmd.Stdout = os.Stdout
cmd.Stderr = os.Stderr
err := cmd.Run()
return editorFinishedMsg{err: err}
}
}Critical: For vim/interactive editors, you must connect stdin/stdout/stderr or the editor won't work properly.
Component Communication
Message-Based Coordination
// Custom messages for component coordination
type (
fileSelectedMsg struct {
file *gitdiff.File
}
diffLoadedMsg struct {
content string
}
)
// Parent handles coordination
func (m Model) Update(msg tea.Msg) (Model, tea.Cmd) {
switch msg := msg.(type) {
case fileSelectedMsg:
// FileTree selected a file, tell DiffViewer
return m, m.diffViewer.LoadFile(msg.file)
}
// Delegate to children
var cmd tea.Cmd
m.fileTree, cmd = m.fileTree.Update(msg)
return m, cmd
}Focus Management
type FocusedPanel int
const (
FocusFileTree FocusedPanel = iota
FocusDiffViewer
)
func (m Model) Update(msg tea.Msg) (Model, tea.Cmd) {
if msg, ok := msg.(tea.KeyPressMsg); ok && msg.Code == tea.KeyTab {
// Switch focus
m.focused = (m.focused + 1) % 2
return m, nil
}
// Only focused component handles input
switch m.focused {
case FocusFileTree:
m.fileTree, cmd = m.fileTree.Update(msg)
case FocusDiffViewer:
m.diffViewer, cmd = m.diffViewer.Update(msg)
}
return m, cmd
}Helper Modal Pattern
For overlays like help dialogs:
type Model struct {
helpDialog *components.HelpDialog
showHelp bool
}
func (m Model) Update(msg tea.Msg) (Model, tea.Cmd) {
// Help dialog intercepts input when visible
if m.showHelp {
if msg, ok := msg.(tea.KeyPressMsg); ok && msg.Code == '?' {
m.showHelp = false
return m, nil
}
// Help dialog handles all input
*m.helpDialog, cmd = m.helpDialog.Update(msg)
return m, cmd
}
// Toggle help
if msg, ok := msg.(tea.KeyPressMsg); ok && msg.Code == '?' {
m.showHelp = true
return m, nil
}
// Normal input handling
// ...
}
func (m Model) View() string {
view := m.renderNormal()
if m.showHelp {
// Overlay help on top
return m.helpDialog.View(view)
}
return view
}Common Pitfalls
❌ Modifying State Outside Update
// BAD: State modified in View
func (m Model) View() string {
m.offset++ // NEVER modify state in View!
return m.render()
}View must be pure - no side effects!
❌ Blocking Operations in Update
// BAD: Blocking I/O in Update
func (m Model) Update(msg tea.Msg) (Model, tea.Cmd) {
content := os.ReadFile("large-file.txt") // BLOCKS UI!
m.content = string(content)
return m, nil
}Use commands for I/O.
❌ Complex Logic in Update
// BAD: 200 lines of logic in Update
func (m Model) Update(msg tea.Msg) (Model, tea.Cmd) {
switch msg := msg.(type) {
case tea.KeyPressMsg:
// ... 200 lines of key handling ...
}
}Extract to helper methods:
func (m Model) Update(msg tea.Msg) (Model, tea.Cmd) {
switch msg := msg.(type) {
case tea.KeyPressMsg:
return m.handleKeyPress(msg)
}
}
func (m Model) handleKeyPress(msg tea.KeyPressMsg) (Model, tea.Cmd) {
// Clear logic here
}Summary
- One component per file with clear boundaries
- Compositor pattern for complex UIs (parent coordinates, children handle specifics)
- All state in Model - no hidden variables
- Commands for async - never block Update
- Cache expensive operations - external tools, rendering
- Mode-based behavior for complex interactions (vim-style)
- Focus management for multi-panel UIs
- Extract helper methods - keep Update readable
- Pure View - no side effects, deterministic output
- Message-based coordination - components communicate via messages