tui

package module
v1.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 20, 2026 License: MIT Imports: 15 Imported by: 0

README

tui

A comprehensive Terminal User Interface framework for building Codex-like CLI experiences with modern, interactive dashboard capabilities.

Overview

tui is a production-ready framework built on top of the SCKelemen visualization stack, providing fully-tested, ready-to-use components for building sophisticated terminal applications with modern UX patterns.

✨ Highlights

  • 🎨 Interactive Dashboards: Responsive grid layouts with real-time metrics, sparklines, and drill-down modals
  • ⌨️ Keyboard Navigation: Full arrow key + vim-style (hjkl) navigation with visual focus indicators
  • 📊 Data Visualization: StatCards with change indicators (↑↓→), trend graphs, and detailed modal views
  • 🎯 Focus Management: Intuitive focus flow with visual states (focused, selected, normal)
  • 📏 Responsive Layouts: Auto-adjusting grids that adapt to terminal size
  • 🧪 Battle-Tested: 446 tests with 83.9% coverage

Features

  • Rich Components: Dashboards, file explorers, command palettes, status bars, modals, code blocks, diffs, confirmations
  • Keyboard Navigation: Arrow keys + vim bindings (hjkl) with customizable keymaps
  • Mouse Support: Click, scroll, drag interactions
  • Focus Management: Visual focus indicators with three states (focused/selected/normal)
  • Layout System: CSS Grid and Flexbox layouts via layout package
  • Theme Support: Full design token integration via design-system
  • Unicode Aware: Proper handling of emoji, wide characters via text
  • Color Science: Perceptually uniform gradients via color (OKLCH)

Architecture

tui (high-level components)
 ├── cli (terminal rendering)
 ├── layout (flexbox/grid)
 ├── design-system (themes)
 ├── text (unicode width)
 └── color (OKLCH gradients)

Installation

go get github.com/SCKelemen/tui@latest

Quick Start

Interactive Dashboard Example
package main

import (
    "github.com/SCKelemen/tui"
    tea "github.com/charmbracelet/bubbletea"
)

type model struct {
    dashboard *tui.Dashboard
}

func (m model) Init() tea.Cmd { return nil }

func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
    switch msg := msg.(type) {
    case tea.WindowSizeMsg:
        m.dashboard.Update(msg)
    case tea.KeyMsg:
        if msg.String() == "q" {
            return m, tea.Quit
        }
        m.dashboard.Update(msg)
    }
    return m, nil
}

func (m model) View() string {
    return m.dashboard.View()
}

func main() {
    // Create stat cards
    cpuCard := tui.NewStatCard(
        tui.WithTitle("CPU Usage"),
        tui.WithValue("42%"),
        tui.WithChange(5, 13.5),
        tui.WithTrend([]float64{35, 38, 40, 42, 45}),
    )

    memoryCard := tui.NewStatCard(
        tui.WithTitle("Memory"),
        tui.WithValue("8.2 GB"),
        tui.WithSubtitle("of 16 GB total"),
        tui.WithChange(-200, -2.4),
    )

    // Create responsive dashboard
    dashboard := tui.NewDashboard(
        tui.WithDashboardTitle("System Metrics"),
        tui.WithResponsiveLayout(30),
        tui.WithCards(cpuCard, memoryCard),
    )
    dashboard.Focus() // Enable keyboard navigation

    p := tea.NewProgram(
        model{dashboard: dashboard},
        tea.WithAltScreen(),
    )
    if _, err := p.Run(); err != nil {
        panic(err)
    }
}

Features shown:

  • ✅ Responsive grid layout
  • ✅ StatCards with values and trends
  • ✅ Change indicators (↑↓→)
  • ✅ Keyboard navigation (arrow keys/hjkl)
  • ✅ Focus management

See examples/dashboard_demo for a complete example with real-time updates!

Components

📊 Dashboard System (Interactive)

Dashboard - Responsive grid container for metrics visualization

  • Keyboard navigation (←→↑↓ or hjkl)
  • Auto-adjusting column layout
  • Real-time updates
  • Focus management

StatCard - Individual metric cards with:

  • Title, value, subtitle
  • Change indicators (↑↓→) with color coding
  • Sparkline trends (▁▂▃▄▅▆▇█)
  • Visual focus states (focused/selected/normal)

DetailModal - Drill-down view for detailed metrics

  • Large 8-line trend graphs
  • Statistics (min, max, avg)
  • Press Enter to open, ESC to close

See DASHBOARD.md for complete documentation.

FileExplorer

Tree view with navigation, search, and file operations.

CommandPalette

Fuzzy-searchable command launcher with keyboard shortcuts.

StatusBar

Bottom status bar with context-aware keybindings and focus indicators.

Modal

Dialog boxes for confirmations, inputs, and detail views.

ActivityBar

Animated status line with spinner, elapsed time, and progress.

ToolBlock

Collapsible content blocks for tool execution results with streaming support.

TextInput

Text input fields with validation and keyboard controls.

Header

Top bar with title, breadcrumbs, and navigation.

StructuredData

Formatted JSON/data display with syntax highlighting.

CodeBlock

Collapsible code display with syntax highlighting, line numbers, and operation indicators (Write, Read, Edit).

DiffBlock

Unified diff viewer with +/- indicators, line numbers, and expand/collapse functionality.

ConfirmationBlock

File operation prompts with code preview, multiple choice options, and keyboard navigation.

See COMPONENTS.md for detailed documentation on all components.

Status & Roadmap

✅ Completed
  • Interactive Dashboard system with keyboard navigation
  • StatCard component with sparklines and change indicators
  • DetailModal for drill-down views
  • Focus management with visual states
  • FileExplorer component
  • StatusBar component
  • CommandPalette component
  • Keyboard navigation (arrow keys + vim bindings)
  • ActivityBar with spinner animations
  • ToolBlock with streaming support
  • Modal dialogs
  • TextInput fields
  • Header component
  • StructuredData display
  • CodeBlock for syntax-highlighted code display
  • DiffBlock for unified diff viewing
  • ConfirmationBlock for file operation prompts
  • Comprehensive test coverage (446 tests, 83.9%)
🚧 In Progress
  • Theme customization and dark/light modes
  • Mouse event handling improvements
  • Additional chart types (bar, pie, gauge)
📋 Planned
  • Window splitting and panes
  • Plugin system
  • Animation system
  • More visualization components

Testing

The library has comprehensive test coverage:

  • 446 total tests across all components
  • 83.9% code coverage
  • 100% component coverage (16 of 16 files tested)
  • Tests for: creation, rendering, updates, focus management, keyboard navigation, edge cases

Run tests:

go test ./...                         # Run all tests
go test -v -run TestDashboard        # Dashboard tests
go test -v -run TestStatCard         # StatCard tests
go test -v -run TestDetailModal      # Modal tests
go test -v -run TestCodeBlock        # CodeBlock tests
go test -v -run TestDiffBlock        # DiffBlock tests
go test -v -run TestConfirmationBlock # ConfirmationBlock tests
go test -cover ./...                 # With coverage report

License

Bearware 1.0

  • cli - Low-level terminal rendering
  • layout - CSS-like layout engine
  • design-system - Design tokens and themes
  • dataviz - Data visualization components

Documentation

Overview

Package tui provides a comprehensive Terminal User Interface framework for building sophisticated CLI applications with modern UX patterns.

The framework is built on top of Bubble Tea and provides high-level components for common UI patterns including interactive dashboards, file explorers, command palettes, status bars, and modal dialogs.

Key features:

  • Interactive dashboards with keyboard navigation and drill-down modals
  • StatCards with sparklines, change indicators, and focus states
  • Command palettes with fuzzy search
  • File explorers with tree navigation
  • Status bars with keybinding hints
  • Modal dialogs for confirmations and details
  • Full keyboard navigation with vim-style bindings
  • Responsive layouts that adapt to terminal size
  • Theme support via design tokens

Architecture:

All components implement the Component interface, which follows the Bubble Tea pattern with Init/Update/View methods plus Focus/Blur/Focused for focus management.

Components can be composed together to build complex UIs. The Application type provides a container for managing multiple components with automatic focus cycling.

Example usage: 

// Create components
dashboard := tui.NewDashboard(
    tui.WithDashboardTitle("Metrics"),
    tui.WithCards(cpuCard, memCard),
)
dashboard.Focus()

statusBar := tui.NewStatusBar()
statusBar.SetMessage("Ready")

// Run with Bubble Tea
p := tea.NewProgram(model{
    dashboard: dashboard,
    statusBar: statusBar,
}, tea.WithAltScreen())
p.Run()

For detailed component documentation, see the individual component types.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// SpinnerDots - Braille dots spinner (smooth)
	SpinnerDots = Spinner{
		Frames: []string{"⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"},
	}

	// SpinnerLine - Classic line spinner
	SpinnerLine = Spinner{
		Frames: []string{"─", "\\", "|", "/"},
	}

	// SpinnerCircle - Rotating circle
	SpinnerCircle = Spinner{
		Frames: []string{"◴", "◷", "◶", "◵"},
	}

	// SpinnerThinking - Codex/Claude-style thinking animation (small to large)
	SpinnerThinking = Spinner{
		Frames: []string{".", "+", "*", "÷", "•"},
	}

	// SpinnerCodexThinking - Codex CLI style thinking animation.
	SpinnerCodexThinking = SpinnerThinking

	// SpinnerClaudeThinking - Backward-compatible alias for SpinnerThinking.
	SpinnerClaudeThinking = SpinnerThinking

	// SpinnerBlink - Simple blink (on/off)
	SpinnerBlink = Spinner{
		Frames: []string{"⏺", " "},
	}

	// SpinnerDotsJumping - Jumping dots
	SpinnerDotsJumping = Spinner{
		Frames: []string{"⢄", "⢂", "⢁", "⡁", "⡈", "⡐", "⡠"},
	}

	// SpinnerArc - Growing arc
	SpinnerArc = Spinner{
		Frames: []string{"◜", "◠", "◝", "◞", "◡", "◟"},
	}

	// SpinnerCircleQuarters - Circle with quarters
	SpinnerCircleQuarters = Spinner{
		Frames: []string{"◐", "◓", "◑", "◒"},
	}

	// SpinnerSquare - Rotating square corners
	SpinnerSquare = Spinner{
		Frames: []string{"◰", "◳", "◲", "◱"},
	}

	// SpinnerArrows - Rotating arrows
	SpinnerArrows = Spinner{
		Frames: []string{"←", "↖", "↑", "↗", "→", "↘", "↓", "↙"},
	}

	// SpinnerBouncingBar - Bouncing bar
	SpinnerBouncingBar = Spinner{
		Frames: []string{"▁", "▂", "▃", "▄", "▅", "▆", "▇", "█", "▇", "▆", "▅", "▄", "▃", "▁"},
	}

	// SpinnerBouncingBall - Bouncing ball
	SpinnerBouncingBall = Spinner{
		Frames: []string{"⠁", "⠂", "⠄", "⡀", "⢀", "⠠", "⠐", "⠈"},
	}

	// SpinnerPulse - Pulsing circle
	SpinnerPulse = Spinner{
		Frames: []string{"○", "◔", "◐", "◕", "●", "◕", "◐", "◔"},
	}
)

Predefined spinner animations

View Source 
var (
	// IconSetDefault - Default icons
	IconSetDefault = IconSet{
		Running: "⏺",
		Success: "⏺",
		Error:   "⏺",
		Warning: "⏺",
		Info:    "⏺",
		None:    "⏺",
	}

	// IconSetSymbols - Unicode symbols
	IconSetSymbols = IconSet{
		Running: "⏺",
		Success: "✓",
		Error:   "✗",
		Warning: "⚠",
		Info:    "ℹ",
		None:    "⏺",
	}

	// IconSetCircles - Circle-based icons
	IconSetCircles = IconSet{
		Running: "○",
		Success: "●",
		Error:   "◯",
		Warning: "◐",
		Info:    "○",
		None:    "○",
	}

	// IconSetEmoji - Emoji icons
	IconSetEmoji = IconSet{
		Running: "⏺",
		Success: "✅",
		Error:   "❌",
		Warning: "⚡",
		Info:    "💡",
		None:    "⏺",
	}

	// IconSetMinimal - Minimal ASCII
	IconSetMinimal = IconSet{
		Running: "·",
		Success: "+",
		Error:   "x",
		Warning: "!",
		Info:    "i",
		None:    "·",
	}

	// IconSetCodex - Codex CLI style
	IconSetCodex = IconSet{
		Running: "⏺",
		Success: "✓",
		Error:   "✗",
		Warning: "⚠",
		Info:    "⏺",
		None:    "⏺",
	}

	// IconSetClaude - Backward-compatible alias for IconSetCodex.
	IconSetClaude = IconSet{
		Running: IconSetCodex.Running,
		Success: IconSetCodex.Success,
		Error:   IconSetCodex.Error,
		Warning: IconSetCodex.Warning,
		Info:    IconSetCodex.Info,
		None:    IconSetCodex.None,
	}
)

Predefined icon sets

View Source 
var LayoutHelpers = NewLayoutHelper()

Global helper instance for convenience

Functions

This section is empty.

Types

type ActivityBar 

type ActivityBar struct {
	// contains filtered or unexported fields
}

ActivityBar displays an animated status line with spinner, elapsed time, and progress

func NewActivityBar 

func NewActivityBar(opts ...ActivityBarOption) *ActivityBar

NewActivityBar creates a new activity bar

func (*ActivityBar) Blur 

func (a *ActivityBar) Blur()

Blur is called when this component loses focus

func (*ActivityBar) Focus 

func (a *ActivityBar) Focus()

Focus is called when this component receives focus

func (*ActivityBar) Focused 

func (a *ActivityBar) Focused() bool

Focused returns whether this component is currently focused

func (*ActivityBar) Init 

func (a *ActivityBar) Init() tea.Cmd

Init initializes the activity bar

func (*ActivityBar) SetProgress 

func (a *ActivityBar) SetProgress(progress string)

SetProgress updates the progress indicator

func (*ActivityBar) Start 

func (a *ActivityBar) Start(message string) tea.Cmd

Start begins the activity animation

func (*ActivityBar) Stop 

func (a *ActivityBar) Stop()

Stop stops the activity animation

func (*ActivityBar) Update 

func (a *ActivityBar) Update(msg tea.Msg) (Component, tea.Cmd)

Update handles messages

func (*ActivityBar) View 

func (a *ActivityBar) View() string

View renders the activity bar

type ActivityBarOption added in v1.1.0 

type ActivityBarOption func(*ActivityBar)

ActivityBarOption configures an ActivityBar.

func WithActivityBarDesignTokens added in v1.1.0 

func WithActivityBarDesignTokens(tokens *design.DesignTokens) ActivityBarOption

WithActivityBarDesignTokens applies design-system colors to the activity bar.

func WithActivityBarTheme added in v1.1.0 

func WithActivityBarTheme(theme string) ActivityBarOption

WithActivityBarTheme applies a named design-system theme.

type Application 

type Application struct {
	// contains filtered or unexported fields
}

Application represents the main TUI application

func NewApplication 

func NewApplication() *Application

NewApplication creates a new TUI application

func (*Application) AddComponent 

func (a *Application) AddComponent(c Component)

AddComponent adds a component to the application

func (*Application) FocusComponent 

func (a *Application) FocusComponent(index int)

FocusComponent focuses a specific component by index, blurring the currently focused one

func (*Application) Init 

func (a *Application) Init() tea.Cmd

Init initializes the application

func (*Application) Update 

func (a *Application) Update(msg tea.Msg) (tea.Model, tea.Cmd)

Update handles messages

func (*Application) View 

func (a *Application) View() string

View renders the application

type CodeBlock 

type CodeBlock struct {
	// contains filtered or unexported fields
}

CodeBlock displays source code with line numbers, syntax highlighting (future), and collapse/expand

func NewCodeBlock 

func NewCodeBlock(opts ...CodeBlockOption) *CodeBlock

NewCodeBlock creates a new code block component

func (*CodeBlock) Blur 

func (cb *CodeBlock) Blur()

Blur is called when this component loses focus

func (*CodeBlock) Collapse 

func (cb *CodeBlock) Collapse()

Collapse hides most of the code

func (*CodeBlock) Expand 

func (cb *CodeBlock) Expand()

Expand shows the full code

func (*CodeBlock) Focus 

func (cb *CodeBlock) Focus()

Focus is called when this component receives focus

func (*CodeBlock) Focused 

func (cb *CodeBlock) Focused() bool

Focused returns whether this component is currently focused

func (*CodeBlock) Init 

func (cb *CodeBlock) Init() tea.Cmd

Init initializes the code block

func (*CodeBlock) IsExpanded 

func (cb *CodeBlock) IsExpanded() bool

IsExpanded returns whether the code is currently expanded

func (*CodeBlock) Toggle 

func (cb *CodeBlock) Toggle()

Toggle expands or collapses the code block

func (*CodeBlock) Update 

func (cb *CodeBlock) Update(msg tea.Msg) (Component, tea.Cmd)

Update handles messages

func (*CodeBlock) View 

func (cb *CodeBlock) View() string

View renders the code block

type CodeBlockOption 

type CodeBlockOption func(*CodeBlock)

CodeBlockOption configures a CodeBlock

func WithCode 

func WithCode(code string) CodeBlockOption

WithCode sets the code content from a single string

func WithCodeFilename 

func WithCodeFilename(name string) CodeBlockOption

WithCodeFilename sets the filename

func WithCodeLines 

func WithCodeLines(lines []string) CodeBlockOption

WithCodeLines sets the code content as lines

func WithCodeMaxLines 

func WithCodeMaxLines(max int) CodeBlockOption

WithCodeMaxLines sets maximum lines to show when expanded

func WithCodeOperation 

func WithCodeOperation(op string) CodeBlockOption

WithCodeOperation sets the operation type (Write, Read, Edit, etc.)

func WithCodeSummary 

func WithCodeSummary(summary string) CodeBlockOption

WithCodeSummary sets the summary text

func WithExpanded 

func WithExpanded(expanded bool) CodeBlockOption

WithExpanded sets whether the block starts expanded

func WithLanguage 

func WithLanguage(lang string) CodeBlockOption

WithLanguage sets the programming language

func WithPreviewLines 

func WithPreviewLines(n int) CodeBlockOption

WithPreviewLines sets number of preview lines when collapsed

func WithStartLine 

func WithStartLine(line int) CodeBlockOption

WithStartLine sets the starting line number

type ColumnAlign 

type ColumnAlign int

ColumnAlign defines how content is aligned within a column 

const (
	AlignLeft ColumnAlign = iota
	AlignCenter
	AlignRight
)

type Command 

type Command struct {
	Name        string         // Display name of the command
	Description string         // Brief description of what the command does
	Category    string         // Category for grouping (e.g., "File", "Edit", "View")
	Action      func() tea.Cmd // Function to execute when command is selected
	Keybinding  string         // Optional keyboard shortcut (e.g., "Ctrl+S")
}

Command represents an executable command in the command palette with metadata for display and categorization.

type CommandPalette 

type CommandPalette struct {
	// contains filtered or unexported fields
}

CommandPalette is a fuzzy-searchable command launcher inspired by VS Code's command palette. It provides a popup interface for quickly executing commands via keyboard.

Features:

  • Fuzzy search filtering
  • Keyboard navigation (↑↓ or j/k)
  • Category grouping
  • Keybinding hints
  • Toggle visibility with Ctrl+K

Example usage: 

commands := []tui.Command{
    {Name: "Save File", Description: "Save current file", Category: "File", Keybinding: "Ctrl+S"},
    {Name: "Open File", Description: "Open a file", Category: "File", Keybinding: "Ctrl+O"},
}
palette := tui.NewCommandPalette(commands)
palette.Show()

func NewCommandPalette 

func NewCommandPalette(commands []Command) *CommandPalette

NewCommandPalette creates a new command palette with the given list of commands. The palette is initially hidden and can be shown/hidden with Show() and Hide(), or toggled with Toggle().

The palette displays up to 8 commands at a time and supports fuzzy searching.

func (*CommandPalette) Blur 

func (cp *CommandPalette) Blur()

Blur is called when this component loses focus

func (*CommandPalette) Focus 

func (cp *CommandPalette) Focus()

Focus is called when this component receives focus

func (*CommandPalette) Focused 

func (cp *CommandPalette) Focused() bool

Focused returns whether this component is currently focused

func (*CommandPalette) Hide 

func (cp *CommandPalette) Hide()

Hide conceals the command palette

func (*CommandPalette) Init 

func (cp *CommandPalette) Init() tea.Cmd

Init initializes the command palette

func (*CommandPalette) IsVisible 

func (cp *CommandPalette) IsVisible() bool

IsVisible returns whether the palette is currently visible

func (*CommandPalette) Show 

func (cp *CommandPalette) Show()

Show displays the command palette

func (*CommandPalette) Update 

func (cp *CommandPalette) Update(msg tea.Msg) (Component, tea.Cmd)

Update handles messages

func (*CommandPalette) View 

func (cp *CommandPalette) View() string

View renders the command palette

type Component 

type Component interface {
	// Init initializes the component
	Init() tea.Cmd

	// Update handles messages and updates component state
	Update(msg tea.Msg) (Component, tea.Cmd)

	// View renders the component
	View() string

	// Focus is called when this component receives focus
	Focus()

	// Blur is called when this component loses focus
	Blur()

	// Focused returns whether this component is currently focused
	Focused() bool
}

Component is the interface all TUI components must implement

type ConfirmationBlock 

type ConfirmationBlock struct {
	// contains filtered or unexported fields
}

ConfirmationBlock displays file operations with code preview and multiple choice confirmation

func NewConfirmationBlock 

func NewConfirmationBlock(opts ...ConfirmationBlockOption) *ConfirmationBlock

NewConfirmationBlock creates a new confirmation block

func (*ConfirmationBlock) Blur 

func (cb *ConfirmationBlock) Blur()

Blur is called when this component loses focus

func (*ConfirmationBlock) Focus 

func (cb *ConfirmationBlock) Focus()

Focus is called when this component receives focus

func (*ConfirmationBlock) Focused 

func (cb *ConfirmationBlock) Focused() bool

Focused returns whether this component is currently focused

func (*ConfirmationBlock) GetSelection 

func (cb *ConfirmationBlock) GetSelection() int

GetSelection returns the selected option index (-1 if cancelled)

func (*ConfirmationBlock) Init 

func (cb *ConfirmationBlock) Init() tea.Cmd

Init initializes the confirmation block

func (*ConfirmationBlock) IsConfirmed 

func (cb *ConfirmationBlock) IsConfirmed() bool

IsConfirmed returns whether the user has made a choice

func (*ConfirmationBlock) Reset 

func (cb *ConfirmationBlock) Reset()

Reset resets the confirmation state

func (*ConfirmationBlock) Update 

func (cb *ConfirmationBlock) Update(msg tea.Msg) (Component, tea.Cmd)

Update handles messages

func (*ConfirmationBlock) View 

func (cb *ConfirmationBlock) View() string

View renders the confirmation block

type ConfirmationBlockOption 

type ConfirmationBlockOption func(*ConfirmationBlock)

ConfirmationBlockOption configures a ConfirmationBlock

func WithConfirmCode 

func WithConfirmCode(code string) ConfirmationBlockOption

WithConfirmCode sets the code content

func WithConfirmCodeLines 

func WithConfirmCodeLines(lines []string) ConfirmationBlockOption

WithConfirmCodeLines sets the code content as lines

func WithConfirmDescription 

func WithConfirmDescription(desc string) ConfirmationBlockOption

WithConfirmDescription sets the description text

func WithConfirmFilepath 

func WithConfirmFilepath(path string) ConfirmationBlockOption

WithConfirmFilepath sets the file path

func WithConfirmFooterHints 

func WithConfirmFooterHints(hints []string) ConfirmationBlockOption

WithConfirmFooterHints sets footer hint text

func WithConfirmOperation 

func WithConfirmOperation(op string) ConfirmationBlockOption

WithConfirmOperation sets the operation type

func WithConfirmOptions 

func WithConfirmOptions(options []string) ConfirmationBlockOption

WithConfirmOptions sets the confirmation options

func WithConfirmPreview 

func WithConfirmPreview(n int) ConfirmationBlockOption

WithConfirmPreview sets number of preview lines (0 = show all)

func WithConfirmStartLine 

func WithConfirmStartLine(line int) ConfirmationBlockOption

WithConfirmStartLine sets the starting line number

type Dashboard 

type Dashboard struct {
	// contains filtered or unexported fields
}

Dashboard displays multiple stat cards in a responsive grid layout with interactive keyboard navigation. It supports arrow keys (←→↑↓) and vim-style (hjkl) navigation, visual focus states, and drill-down modals for detailed metric views.

The dashboard automatically calculates card dimensions based on the terminal size and configured layout (fixed columns or responsive grid). Cards can be navigated using keyboard controls, and pressing Enter on a focused card opens a DetailModal with expanded metrics and trend graphs.

Example usage: 

dashboard := tui.NewDashboard(
    tui.WithDashboardTitle("System Metrics"),
    tui.WithResponsiveLayout(30),
    tui.WithCards(cpuCard, memoryCard, diskCard),
)
dashboard.Focus()

func NewDashboard 

func NewDashboard(opts ...DashboardOption) *Dashboard

NewDashboard creates a new dashboard with the given configuration options.

Defaults:

  • columns: 3
  • gap: 2 characters
  • minCardWidth: 30 characters
  • responsive: true
  • theme: DefaultTheme()

The dashboard automatically focuses the first card if cards are provided. Use WithCards, WithGridColumns, WithResponsiveLayout, and other options to customize.

func (*Dashboard) AddCard 

func (d *Dashboard) AddCard(card *StatCard)

AddCard adds a stat card to the dashboard and updates card dimensions to fit the current layout. Cards are appended to the end of the grid.

func (*Dashboard) Blur 

func (d *Dashboard) Blur()

Blur is called when this component loses focus

func (*Dashboard) Focus 

func (d *Dashboard) Focus()

Focus is called when this component receives focus

func (*Dashboard) Focused 

func (d *Dashboard) Focused() bool

Focused returns whether this component is currently focused

func (*Dashboard) GetCards 

func (d *Dashboard) GetCards() []*StatCard

GetCards returns a slice of all stat cards currently in the dashboard. The returned slice is the internal slice, not a copy.

func (*Dashboard) Init 

func (d *Dashboard) Init() tea.Cmd

Init initializes the dashboard

func (*Dashboard) RemoveCard 

func (d *Dashboard) RemoveCard(index int)

RemoveCard removes a stat card from the dashboard by index and updates card dimensions to fit the new layout. Silently ignores invalid indices.

func (*Dashboard) SetCards 

func (d *Dashboard) SetCards(cards []*StatCard)

SetCards replaces all stat cards in the dashboard and updates card dimensions to fit the new layout.

func (*Dashboard) Update 

func (d *Dashboard) Update(msg tea.Msg) (Component, tea.Cmd)

Update handles Bubble Tea messages including window resize and keyboard navigation.

Window resize messages (tea.WindowSizeMsg) trigger recalculation of card dimensions.

Keyboard controls (when focused):

  • ←, h: Move focus left
  • →, l: Move focus right
  • ↑, k: Move focus up (grid-aware)
  • ↓, j: Move focus down (grid-aware)
  • Enter: Open DetailModal for focused card
  • ESC: Clear selection

When the DetailModal is visible, all keyboard input is forwarded to it. When the modal closes, focus returns to the dashboard.

func (*Dashboard) View 

func (d *Dashboard) View() string

View renders the dashboard as a string, displaying all cards in a grid layout.

If a DetailModal is visible, it is overlayed on top of the dashboard view. The rendering uses line-by-line compositing to merge the modal and dashboard views.

Returns an empty string if the dashboard width is zero or there are no cards.

type DashboardOption 

type DashboardOption func(*Dashboard)

DashboardOption configures a Dashboard

func WithCards 

func WithCards(cards ...*StatCard) DashboardOption

WithCards sets the stat cards to display

func WithDashboardTitle 

func WithDashboardTitle(title string) DashboardOption

WithDashboardTitle sets the dashboard title

func WithGap 

func WithGap(gap float64) DashboardOption

WithGap sets the gap between cards

func WithGridColumns 

func WithGridColumns(columns int) DashboardOption

WithGridColumns sets the number of columns in the grid

func WithResponsiveLayout 

func WithResponsiveLayout(minCardWidth float64) DashboardOption

WithResponsiveLayout enables responsive grid layout

type DataItem 

type DataItem struct {
	Type   ItemType
	Key    string
	Value  string
	Indent int    // Indentation level (0 = no indent, 1 = one level, etc.)
	Color  string // Optional ANSI color code (e.g., "\033[32m" for green)
}

DataItem represents a single item in structured data

type DataStatus 

type DataStatus int

DataStatus represents the status of the data display 

const (
	DataStatusNone DataStatus = iota
	DataStatusRunning
	DataStatusSuccess
	DataStatusError
	DataStatusWarning
	DataStatusInfo
)

type DetailModal 

type DetailModal struct {
	// contains filtered or unexported fields
}

DetailModal displays detailed information about a StatCard in a centered overlay modal. It shows expanded metrics including an 8-line trend graph, statistics (min, max, avg), change indicators, and optional historical data.

The modal is typically opened by pressing Enter on a focused card in a Dashboard. It can be closed by pressing ESC or 'q'.

Visual layout:

  • Centered at 70% width and 80% height of the viewport
  • Double-line borders with title
  • Large 8-line trend graph using Unicode blocks (▀▄█)
  • Statistics section (min, max, average)
  • Optional historical data section

Example usage: 

modal := tui.NewDetailModal()
modal.SetContent(statCard)
modal.Show() // Opens the modal
// ... user closes with ESC
modal.IsVisible() // Returns false after close

func NewDetailModal 

func NewDetailModal(opts ...DetailModalOption) *DetailModal

NewDetailModal creates a new detail modal with the given configuration options.

The modal is initially hidden and must be shown with Show(). Use SetContent to populate the modal with data from a StatCard, then Show() to display it.

Defaults:

  • visible: false
  • theme: DefaultTheme()
  • history: empty slice

func (*DetailModal) Blur 

func (m *DetailModal) Blur()

Blur is called when this component loses focus

func (*DetailModal) Focus 

func (m *DetailModal) Focus()

Focus is called when this component receives focus

func (*DetailModal) Focused 

func (m *DetailModal) Focused() bool

Focused returns whether this component is currently focused

func (*DetailModal) Hide 

func (m *DetailModal) Hide()

Hide hides the modal and removes focus. This is typically called when the user presses ESC or 'q' to close the modal.

func (*DetailModal) Init 

func (m *DetailModal) Init() tea.Cmd

Init initializes the modal

func (*DetailModal) IsVisible 

func (m *DetailModal) IsVisible() bool

IsVisible returns whether the modal is visible

func (*DetailModal) SetContent 

func (m *DetailModal) SetContent(card *StatCard)

SetContent updates the modal content from a StatCard, copying all relevant fields including title, value, subtitle, change data, trend data, and colors. This should be called before Show() to populate the modal with the card's data.

func (*DetailModal) Show 

func (m *DetailModal) Show()

Show displays the modal and sets it as focused. Call this after populating the modal with SetContent to display it to the user.

func (*DetailModal) Update 

func (m *DetailModal) Update(msg tea.Msg) (Component, tea.Cmd)

Update handles Bubble Tea messages including window resize and keyboard input.

Window resize messages (tea.WindowSizeMsg) update the modal's dimensions for centering.

Keyboard controls (when visible and focused):

  • ESC, q: Close the modal

Messages are only processed when the modal is both visible and focused.

func (*DetailModal) View 

func (m *DetailModal) View() string

View renders the modal as a centered overlay. Returns an empty string if the modal is not visible or width is zero.

The modal is sized at 70% of viewport width (minimum 60 chars) and 80% of viewport height (minimum 20 lines), and centered both horizontally and vertically.

type DetailModalOption 

type DetailModalOption func(*DetailModal)

DetailModalOption configures a DetailModal

func WithHistory 

func WithHistory(history []string) DetailModalOption

WithHistory sets historical data points

func WithModalContent 

func WithModalContent(card *StatCard) DetailModalOption

WithModalContent sets the content from a StatCard

type DiffBlock 

type DiffBlock struct {
	// contains filtered or unexported fields
}

DiffBlock displays code changes with +/- indicators

func NewDiffBlock 

func NewDiffBlock(opts ...DiffBlockOption) *DiffBlock

NewDiffBlock creates a new diff block component

func NewDiffBlockFromStrings 

func NewDiffBlockFromStrings(old, new string, opts ...DiffBlockOption) *DiffBlock

NewDiffBlockFromStrings creates a diff block from old and new content strings

func (*DiffBlock) Blur 

func (db *DiffBlock) Blur()

Blur is called when this component loses focus

func (*DiffBlock) Collapse 

func (db *DiffBlock) Collapse()

Collapse hides the diff

func (*DiffBlock) Expand 

func (db *DiffBlock) Expand()

Expand shows the full diff

func (*DiffBlock) Focus 

func (db *DiffBlock) Focus()

Focus is called when this component receives focus

func (*DiffBlock) Focused 

func (db *DiffBlock) Focused() bool

Focused returns whether this component is currently focused

func (*DiffBlock) Init 

func (db *DiffBlock) Init() tea.Cmd

Init initializes the diff block

func (*DiffBlock) IsExpanded 

func (db *DiffBlock) IsExpanded() bool

IsExpanded returns whether the diff is currently expanded

func (*DiffBlock) Toggle 

func (db *DiffBlock) Toggle()

Toggle expands or collapses the diff block

func (*DiffBlock) Update 

func (db *DiffBlock) Update(msg tea.Msg) (Component, tea.Cmd)

Update handles messages

func (*DiffBlock) View 

func (db *DiffBlock) View() string

View renders the diff block

type DiffBlockOption 

type DiffBlockOption func(*DiffBlock)

DiffBlockOption configures a DiffBlock

func WithDiffContext 

func WithDiffContext(n int) DiffBlockOption

WithDiffContext sets number of context lines

func WithDiffExpanded 

func WithDiffExpanded(expanded bool) DiffBlockOption

WithDiffExpanded sets whether the block starts expanded

func WithDiffFilename 

func WithDiffFilename(name string) DiffBlockOption

WithDiffFilename sets the filename

func WithDiffLines 

func WithDiffLines(lines []DiffLine) DiffBlockOption

WithDiffLines sets the diff content

func WithDiffMaxLines 

func WithDiffMaxLines(max int) DiffBlockOption

WithDiffMaxLines sets maximum lines to show

func WithDiffOperation 

func WithDiffOperation(op string) DiffBlockOption

WithDiffOperation sets the operation type

func WithDiffSummary 

func WithDiffSummary(summary string) DiffBlockOption

WithDiffSummary sets the summary text

type DiffLine 

type DiffLine struct {
	Type    DiffType // Added, Removed, or Unchanged
	Content string   // Line content
	LineNum int      // Line number (for context)
}

DiffLine represents a single line in a diff

type DiffType 

type DiffType int

DiffType indicates the type of diff line 

const (
	DiffUnchanged DiffType = iota // No change (context)
	DiffAdded                     // Line was added (+)
	DiffRemoved                   // Line was removed (-)
)

type FileExplorer 

type FileExplorer struct {
	// contains filtered or unexported fields
}

FileExplorer displays a navigable file tree

func NewFileExplorer 

func NewFileExplorer(path string, opts ...FileExplorerOption) *FileExplorer

NewFileExplorer creates a new file explorer starting at the given path

func (*FileExplorer) Blur 

func (fe *FileExplorer) Blur()

Blur is called when this component loses focus

func (*FileExplorer) Focus 

func (fe *FileExplorer) Focus()

Focus is called when this component receives focus

func (*FileExplorer) Focused 

func (fe *FileExplorer) Focused() bool

Focused returns whether this component is currently focused

func (*FileExplorer) GetSelectedNode 

func (fe *FileExplorer) GetSelectedNode() *FileNode

GetSelectedNode returns the currently selected node

func (*FileExplorer) GetSelectedPath 

func (fe *FileExplorer) GetSelectedPath() string

GetSelectedPath returns the path of the currently selected node

func (*FileExplorer) Init 

func (fe *FileExplorer) Init() tea.Cmd

Init initializes the file explorer

func (*FileExplorer) Update 

func (fe *FileExplorer) Update(msg tea.Msg) (Component, tea.Cmd)

Update handles messages

func (*FileExplorer) View 

func (fe *FileExplorer) View() string

View renders the file explorer

type FileExplorerOption 

type FileExplorerOption func(*FileExplorer)

FileExplorerOption configures a FileExplorer

func WithShowHidden 

func WithShowHidden(show bool) FileExplorerOption

WithShowHidden shows hidden files (starting with .)

type FileNode 

type FileNode struct {
	Name     string
	Path     string
	IsDir    bool
	Children []*FileNode
	Expanded bool
	Parent   *FileNode
}

FileNode represents a file or directory in the tree 

type Header struct {
	// contains filtered or unexported fields
}

Header displays a multi-column header using the layout system

func NewHeader 

func NewHeader(opts ...HeaderOption) *Header

NewHeader creates a new header component

func (*Header) Blur 

func (h *Header) Blur()

Blur is called when this component loses focus

func (*Header) Focus 

func (h *Header) Focus()

Focus is called when this component receives focus

func (*Header) Focused 

func (h *Header) Focused() bool

Focused returns whether this component is currently focused

func (*Header) Init 

func (h *Header) Init() tea.Cmd

Init initializes the header

func (*Header) Update 

func (h *Header) Update(msg tea.Msg) (Component, tea.Cmd)

Update handles messages

func (*Header) View 

func (h *Header) View() string

View renders the header

type HeaderColumn 

type HeaderColumn struct {
	Width   int         // Flex-grow value (0 = equal distribution with others)
	Align   ColumnAlign // Content alignment
	Content []string    // Lines of content
}

HeaderColumn represents a column in the header

type HeaderOption 

type HeaderOption func(*Header)

HeaderOption configures a Header

func WithColumnSections 

func WithColumnSections(columnIndex int, sections ...HeaderSection) HeaderOption

WithColumnSections sets sections for a specific column

func WithColumns 

func WithColumns(columns ...HeaderColumn) HeaderOption

WithColumns sets the columns for the header

func WithVerticalDivider 

func WithVerticalDivider(show bool) HeaderOption

WithVerticalDivider enables/disables the vertical divider between columns

type HeaderSection 

type HeaderSection struct {
	Title   string   // Section title (optional)
	Content []string // Section content lines
	Divider bool     // Show horizontal divider before section
}

HeaderSection represents a section within a column with optional divider

type IconSet 

type IconSet struct {
	Running string
	Success string
	Error   string
	Warning string
	Info    string
	None    string
}

IconSet defines icons for different statuses

type ItemType 

type ItemType int

ItemType represents the type of data item 

const (
	ItemKeyValue ItemType = iota
	ItemHeader
	ItemSeparator
	ItemValue // Value only, no key
)

type LayoutHelper 

type LayoutHelper struct{}

LayoutHelper provides common layout patterns and utilities

func NewLayoutHelper 

func NewLayoutHelper() *LayoutHelper

NewLayoutHelper creates a new layout helper

func (*LayoutHelper) AbsolutePosition 

func (h *LayoutHelper) AbsolutePosition(top, left, width, height float64) *layout.Node

AbsolutePosition creates a node with absolute positioning Useful for overlays, tooltips, floating elements

func (*LayoutHelper) CardLayout 

func (h *LayoutHelper) CardLayout(paddingCh float64) *layout.Node

CardLayout creates a card-style container with padding and borders paddingCh is padding in characters

func (*LayoutHelper) CenteredContent 

func (h *LayoutHelper) CenteredContent() *layout.Node

CenteredContent creates a container with centered content

func (*LayoutHelper) CenteredOverlay 

func (h *LayoutHelper) CenteredOverlay(width, height float64) *layout.Node

CenteredOverlay creates a centered overlay node (perfect for modals, dialogs) width and height are in viewport units (e.g., 60, 20 for 60ch x 20ch)

func (*LayoutHelper) FixedSizeNode 

func (h *LayoutHelper) FixedSizeNode(width, height float64) *layout.Node

FixedSizeNode creates a node with fixed width and height

func (*LayoutHelper) FlexGrowNode 

func (h *LayoutHelper) FlexGrowNode(grow float64) *layout.Node

FlexGrowNode creates a simple node that grows to fill available space

func (*LayoutHelper) GridLayout 

func (h *LayoutHelper) GridLayout(columns int, gap float64) *layout.Node

GridLayout creates a CSS Grid layout with specified columns and rows columns is the number of columns, gap is the spacing between cells

func (*LayoutHelper) HeaderContentFooterLayout 

func (h *LayoutHelper) HeaderContentFooterLayout(headerHeight, footerHeight float64) *layout.Node

HeaderContentFooterLayout creates a classic header/content/footer layout headerHeight and footerHeight are in characters

func (*LayoutHelper) HorizontalStackLayout 

func (h *LayoutHelper) HorizontalStackLayout(gap float64) *layout.Node

HorizontalStackLayout creates a horizontal stack with gap between items

func (*LayoutHelper) ResponsiveGridLayout 

func (h *LayoutHelper) ResponsiveGridLayout(minCardWidth, gap float64) *layout.Node

ResponsiveGridLayout creates a grid that adapts to viewport width minCardWidth is the minimum width for each card in characters gap is the spacing between cards

func (*LayoutHelper) SidebarLayout 

func (h *LayoutHelper) SidebarLayout(sidebarWidth float64) *layout.Node

SidebarLayout creates a sidebar + main content layout sidebarWidth is in characters (e.g., 20 for 20ch)

func (*LayoutHelper) SpaceBetweenRow 

func (h *LayoutHelper) SpaceBetweenRow() *layout.Node

SpaceBetweenRow creates a row with space-between justification Perfect for toolbars, headers with left/right content

func (*LayoutHelper) StackLayout 

func (h *LayoutHelper) StackLayout(gap float64) *layout.Node

StackLayout creates a vertical stack with gap between items

func (*LayoutHelper) ThreeColumnLayout 

func (h *LayoutHelper) ThreeColumnLayout(leftRatio, centerRatio, rightRatio float64) *layout.Node

ThreeColumnLayout creates a three-column layout with adjustable ratios

func (*LayoutHelper) TwoColumnLayout 

func (h *LayoutHelper) TwoColumnLayout(leftRatio, rightRatio float64) *layout.Node

TwoColumnLayout creates a two-column layout with adjustable ratio leftRatio:rightRatio determines the flex-grow distribution (e.g., 1:2) 

type Modal struct {
	// contains filtered or unexported fields
}

Modal displays overlay dialogs for user interaction

func NewModal 

func NewModal(opts ...ModalOption) *Modal

NewModal creates a new modal dialog

func (*Modal) Blur 

func (m *Modal) Blur()

Blur is called when this component loses focus

func (*Modal) Focus 

func (m *Modal) Focus()

Focus is called when this component receives focus

func (*Modal) Focused 

func (m *Modal) Focused() bool

Focused returns whether this component is currently focused

func (*Modal) Hide 

func (m *Modal) Hide()

Hide conceals the modal

func (*Modal) Init 

func (m *Modal) Init() tea.Cmd

Init initializes the modal

func (*Modal) IsVisible 

func (m *Modal) IsVisible() bool

IsVisible returns whether the modal is currently visible

func (*Modal) SetMessage 

func (m *Modal) SetMessage(message string)

SetMessage updates the modal message

func (*Modal) SetTitle 

func (m *Modal) SetTitle(title string)

SetTitle updates the modal title

func (*Modal) Show 

func (m *Modal) Show()

Show displays the modal

func (*Modal) ShowAlert 

func (m *Modal) ShowAlert(title, message string, onOK func() tea.Cmd)

ShowAlert displays an alert modal

func (*Modal) ShowConfirm 

func (m *Modal) ShowConfirm(title, message string, onYes, onNo func() tea.Cmd)

ShowConfirm displays a confirmation modal

func (*Modal) ShowInput 

func (m *Modal) ShowInput(title, message, placeholder string, onOK func(string) tea.Cmd, onCancel func() tea.Cmd)

ShowInput displays an input modal

func (*Modal) Update 

func (m *Modal) Update(msg tea.Msg) (Component, tea.Cmd)

Update handles messages

func (*Modal) View 

func (m *Modal) View() string

View renders the modal

type ModalButton 

type ModalButton struct {
	Label  string
	Action func(string) tea.Cmd // Input value passed for ModalInput, empty string otherwise
}

ModalButton represents a button in the modal

type ModalOption 

type ModalOption func(*Modal)

ModalOption configures a Modal

func WithModalButtons 

func WithModalButtons(buttons []ModalButton) ModalOption

WithModalButtons sets custom buttons

func WithModalInput 

func WithModalInput(placeholder string) ModalOption

WithModalInput enables text input (for ModalInput type)

func WithModalMessage 

func WithModalMessage(message string) ModalOption

WithModalMessage sets the modal message

func WithModalOnCancel 

func WithModalOnCancel(fn func() tea.Cmd) ModalOption

WithModalOnCancel sets the cancel callback

func WithModalOnConfirm 

func WithModalOnConfirm(fn func(string) tea.Cmd) ModalOption

WithModalOnConfirm sets the confirm callback

func WithModalTitle 

func WithModalTitle(title string) ModalOption

WithModalTitle sets the modal title

func WithModalType 

func WithModalType(t ModalType) ModalOption

WithModalType sets the modal type

type ModalType 

type ModalType int

ModalType defines the type of modal dialog 

const (
	// ModalAlert shows a message with an OK button
	ModalAlert ModalType = iota
	// ModalConfirm shows a message with Yes/No or OK/Cancel buttons
	ModalConfirm
	// ModalInput shows a message with a text input field
	ModalInput
)

type Spinner 

type Spinner struct {
	Frames []string
}

Spinner defines an animation sequence

func (Spinner) FrameCount 

func (s Spinner) FrameCount() int

FrameCount returns the number of frames in the spinner

func (Spinner) GetFrame 

func (s Spinner) GetFrame(index int) string

GetFrame returns the frame at the given index

type StatCard 

type StatCard struct {
	// contains filtered or unexported fields
}

StatCard displays a single metric with title, value, change indicator, and optional sparkline trend visualization. Cards support three visual states:

  • Normal: Thin single-line borders (┌─┐)
  • Focused: Double-line cyan borders (╔═╗)
  • Selected: Thick yellow borders (┏━┓)

StatCards are typically used within a Dashboard for displaying multiple metrics in a grid layout. They render change indicators with directional arrows (↑↓→) and optional Unicode sparklines using block characters (▁▂▃▄▅▆▇█).

Example usage: 

card := tui.NewStatCard(
    tui.WithTitle("CPU Usage"),
    tui.WithValue("42%"),
    tui.WithChange(5, 13.5),
    tui.WithTrend([]float64{35, 38, 40, 42, 45}),
)

func NewStatCard 

func NewStatCard(opts ...StatCardOption) *StatCard

NewStatCard creates a new stat card with the given configuration options.

Defaults:

  • width: 30 characters
  • height: 8 lines
  • color: #2196F3 (blue)
  • trendColor: #4CAF50 (green)
  • theme: DefaultTheme()

Use WithTitle, WithValue, WithChange, WithTrend, and other options to customize the card's content and appearance.

func (*StatCard) Blur 

func (s *StatCard) Blur()

Blur is called when this component loses focus

func (*StatCard) Deselect 

func (s *StatCard) Deselect()

Deselect marks the card as not selected

func (*StatCard) Focus 

func (s *StatCard) Focus()

Focus is called when this component receives focus

func (*StatCard) Focused 

func (s *StatCard) Focused() bool

Focused returns whether this component is currently focused

func (*StatCard) Init 

func (s *StatCard) Init() tea.Cmd

Init initializes the stat card

func (*StatCard) IsSelected 

func (s *StatCard) IsSelected() bool

IsSelected returns whether this card is selected

func (*StatCard) Select 

func (s *StatCard) Select()

Select marks the card as selected (for drill-down)

func (*StatCard) Update 

func (s *StatCard) Update(msg tea.Msg) (Component, tea.Cmd)

Update handles Bubble Tea messages. Currently only processes window resize messages (tea.WindowSizeMsg) to update the card's width and height. Individual cards typically don't handle resize directly as the Dashboard manages their dimensions.

func (*StatCard) View 

func (s *StatCard) View() string

View renders the stat card as a bordered box containing the title, value, change indicator, and optional sparkline. The border style changes based on focus and selection state. Returns an empty string if width is zero.

type StatCardOption 

type StatCardOption func(*StatCard)

StatCardOption configures a StatCard

func WithChange 

func WithChange(change int, changePct float64) StatCardOption

WithChange sets the change value and percentage

func WithColor 

func WithColor(color string) StatCardOption

WithColor sets the accent color

func WithSubtitle 

func WithSubtitle(subtitle string) StatCardOption

WithSubtitle sets the subtitle/description

func WithTitle 

func WithTitle(title string) StatCardOption

WithTitle sets the card title

func WithTrend 

func WithTrend(trend []float64) StatCardOption

WithTrend sets the sparkline trend data

func WithTrendColor 

func WithTrendColor(color string) StatCardOption

WithTrendColor sets the trend line color

func WithValue 

func WithValue(value string) StatCardOption

WithValue sets the main value to display

type StatusBar 

type StatusBar struct {
	// contains filtered or unexported fields
}

StatusBar displays status information and keybindings at the bottom of the screen. It shows a status message on the left and keybinding hints on the right, with automatic truncation when the terminal is narrow.

Visual styling changes based on focus state:

  • Focused: Inverted colors (black on white)
  • Unfocused: Dimmed text

Example usage: 

statusBar := tui.NewStatusBar()
statusBar.SetMessage("Processing...")
// Later: statusBar.SetMessage("Complete!")

func NewStatusBar 

func NewStatusBar(opts ...StatusBarOption) *StatusBar

NewStatusBar creates a new status bar with the default message "Ready".

func (*StatusBar) Blur 

func (s *StatusBar) Blur()

Blur is called when this component loses focus

func (*StatusBar) Focus 

func (s *StatusBar) Focus()

Focus is called when this component receives focus

func (*StatusBar) Focused 

func (s *StatusBar) Focused() bool

Focused returns whether this component is currently focused

func (*StatusBar) Init 

func (s *StatusBar) Init() tea.Cmd

Init initializes the status bar

func (*StatusBar) SetMessage 

func (s *StatusBar) SetMessage(msg string)

SetMessage updates the status message displayed on the left side of the status bar. The message will be automatically truncated with "..." if the terminal is too narrow to display both the message and keybinding hints.

func (*StatusBar) Update 

func (s *StatusBar) Update(msg tea.Msg) (Component, tea.Cmd)

Update handles messages

func (*StatusBar) View 

func (s *StatusBar) View() string

View renders the status bar as a single line with the status message on the left and keybinding hints on the right. The message is automatically truncated with "..." if the terminal is too narrow. Returns an empty string if width is zero.

type StatusBarOption added in v1.1.0 

type StatusBarOption func(*StatusBar)

StatusBarOption configures a StatusBar.

func WithStatusBarDesignTokens added in v1.1.0 

func WithStatusBarDesignTokens(tokens *design.DesignTokens) StatusBarOption

WithStatusBarDesignTokens applies design-system colors to the status bar.

func WithStatusBarTheme added in v1.1.0 

func WithStatusBarTheme(theme string) StatusBarOption

WithStatusBarTheme applies a named design-system theme.

type StructuredData 

type StructuredData struct {
	// contains filtered or unexported fields
}

StructuredData displays formatted key-value data with tree connectors

func FromKeyValuePairs 

func FromKeyValuePairs(title string, pairs ...string) *StructuredData

FromKeyValuePairs creates structured data from alternating key-value strings

func FromMap 

func FromMap(title string, data map[string]string) *StructuredData

FromMap creates structured data from a map

func NewStructuredData 

func NewStructuredData(title string, opts ...StructuredDataOption) *StructuredData

NewStructuredData creates a new structured data component

func (*StructuredData) AddColoredRow 

func (sd *StructuredData) AddColoredRow(key, value, color string) *StructuredData

AddColoredRow adds a key-value row with custom color

func (*StructuredData) AddHeader 

func (sd *StructuredData) AddHeader(text string) *StructuredData

AddHeader adds a section header

func (*StructuredData) AddIndentedRow 

func (sd *StructuredData) AddIndentedRow(key, value string, indent int) *StructuredData

AddIndentedRow adds an indented key-value row

func (*StructuredData) AddIndentedValue 

func (sd *StructuredData) AddIndentedValue(value string, indent int) *StructuredData

AddIndentedValue adds an indented value-only line

func (*StructuredData) AddRow 

func (sd *StructuredData) AddRow(key, value string) *StructuredData

AddRow adds a key-value row

func (*StructuredData) AddSeparator 

func (sd *StructuredData) AddSeparator() *StructuredData

AddSeparator adds a blank line

func (*StructuredData) AddValue 

func (sd *StructuredData) AddValue(value string) *StructuredData

AddValue adds a value-only line (no key)

func (*StructuredData) Blur 

func (sd *StructuredData) Blur()

Blur is called when this component loses focus

func (*StructuredData) Clear 

func (sd *StructuredData) Clear() *StructuredData

Clear removes all items

func (*StructuredData) Focus 

func (sd *StructuredData) Focus()

Focus is called when this component receives focus

func (*StructuredData) Focused 

func (sd *StructuredData) Focused() bool

Focused returns whether this component is currently focused

func (*StructuredData) GetStatus 

func (sd *StructuredData) GetStatus() DataStatus

GetStatus returns the current status

func (*StructuredData) Init 

func (sd *StructuredData) Init() tea.Cmd

Init initializes the structured data component

func (*StructuredData) MarkError 

func (sd *StructuredData) MarkError()

MarkError sets status to error (red icon, no animation)

func (*StructuredData) MarkInfo 

func (sd *StructuredData) MarkInfo()

MarkInfo sets status to info (white icon, no animation)

func (*StructuredData) MarkSuccess 

func (sd *StructuredData) MarkSuccess()

MarkSuccess sets status to success (green icon, no animation)

func (*StructuredData) MarkWarning 

func (sd *StructuredData) MarkWarning()

MarkWarning sets status to warning (yellow icon, no animation)

func (*StructuredData) SetExpanded 

func (sd *StructuredData) SetExpanded(expanded bool)

SetExpanded sets the expanded state

func (*StructuredData) SetItems 

func (sd *StructuredData) SetItems(items []DataItem) *StructuredData

SetItems replaces all items (for batch operations)

func (*StructuredData) SetStatus 

func (sd *StructuredData) SetStatus(status DataStatus) tea.Cmd

SetStatus sets the status and starts/stops animation

func (*StructuredData) StartRunning 

func (sd *StructuredData) StartRunning() tea.Cmd

StartRunning sets status to running and begins animation

func (*StructuredData) ToggleExpanded 

func (sd *StructuredData) ToggleExpanded()

ToggleExpanded toggles the expanded state

func (*StructuredData) Update 

func (sd *StructuredData) Update(msg tea.Msg) (Component, tea.Cmd)

Update handles messages

func (*StructuredData) View 

func (sd *StructuredData) View() string

View renders the structured data

type StructuredDataOption 

type StructuredDataOption func(*StructuredData)

StructuredDataOption configures a StructuredData

func WithIconSet 

func WithIconSet(iconSet IconSet) StructuredDataOption

WithIconSet sets the icon set for status indicators

func WithKeyWidth 

func WithKeyWidth(width int) StructuredDataOption

WithKeyWidth sets a fixed width for the key column

func WithRunningColor 

func WithRunningColor(color string) StructuredDataOption

WithRunningColor sets the color for the running status animation

func WithSpinner 

func WithSpinner(spinner Spinner) StructuredDataOption

WithSpinner sets the spinner animation

func WithStructuredDataDesignTokens added in v1.1.0 

func WithStructuredDataDesignTokens(tokens *design.DesignTokens) StructuredDataOption

WithStructuredDataDesignTokens applies design-system colors to status rendering.

func WithStructuredDataIcon 

func WithStructuredDataIcon(icon string) StructuredDataOption

WithIcon sets a custom icon

func WithStructuredDataMaxLines 

func WithStructuredDataMaxLines(n int) StructuredDataOption

WithMaxLines sets the maximum lines to show when collapsed

func WithStructuredDataTheme added in v1.1.0 

func WithStructuredDataTheme(theme string) StructuredDataOption

WithStructuredDataTheme applies a named design-system theme. Supported names: default, midnight, nord, paper, wrapped.

type TextInput 

type TextInput struct {
	// contains filtered or unexported fields
}

TextInput is a multi-line text input component for user messages

func NewTextInput 

func NewTextInput() *TextInput

NewTextInput creates a new text input component

func (*TextInput) Blur 

func (t *TextInput) Blur()

Blur is called when this component loses focus

func (*TextInput) Focus 

func (t *TextInput) Focus()

Focus is called when this component receives focus

func (*TextInput) Focused 

func (t *TextInput) Focused() bool

Focused returns whether this component is currently focused

func (*TextInput) Init 

func (t *TextInput) Init() tea.Cmd

Init initializes the text input

func (*TextInput) OnSubmit 

func (t *TextInput) OnSubmit(fn func(string) tea.Cmd)

OnSubmit sets the callback for when text is submitted

func (*TextInput) Reset 

func (t *TextInput) Reset()

Reset clears the text input

func (*TextInput) SetValue 

func (t *TextInput) SetValue(value string)

SetValue sets the text value

func (*TextInput) Update 

func (t *TextInput) Update(msg tea.Msg) (Component, tea.Cmd)

Update handles messages

func (*TextInput) Value 

func (t *TextInput) Value() string

Value returns the current text value

func (*TextInput) View 

func (t *TextInput) View() string

View renders the text input

type ToolBlock 

type ToolBlock struct {
	// contains filtered or unexported fields
}

ToolBlock represents a collapsible block showing tool execution results

func NewToolBlock 

func NewToolBlock(toolName, command string, output []string, opts ...ToolBlockOption) *ToolBlock

NewToolBlock creates a new tool block

func (*ToolBlock) AppendLine 

func (tb *ToolBlock) AppendLine(line string)

AppendLine adds a single line to the output (for streaming)

func (*ToolBlock) AppendLines 

func (tb *ToolBlock) AppendLines(lines []string)

AppendLines adds multiple lines to the output (for streaming)

func (*ToolBlock) Blur 

func (tb *ToolBlock) Blur()

Blur is called when this component loses focus

func (*ToolBlock) Focus 

func (tb *ToolBlock) Focus()

Focus is called when this component receives focus

func (*ToolBlock) Focused 

func (tb *ToolBlock) Focused() bool

Focused returns whether this component is currently focused

func (*ToolBlock) Init 

func (tb *ToolBlock) Init() tea.Cmd

Init initializes the tool block

func (*ToolBlock) SetExpanded 

func (tb *ToolBlock) SetExpanded(expanded bool)

SetExpanded sets the expanded state

func (*ToolBlock) SetStatus 

func (tb *ToolBlock) SetStatus(status ToolBlockStatus)

SetStatus updates the status and stops streaming if completed

func (*ToolBlock) StartStreaming 

func (tb *ToolBlock) StartStreaming() tea.Cmd

StartStreaming begins streaming mode with running status

func (*ToolBlock) StopStreaming 

func (tb *ToolBlock) StopStreaming()

StopStreaming stops streaming and sets status to complete

func (*ToolBlock) StopStreamingWithError 

func (tb *ToolBlock) StopStreamingWithError()

StopStreamingWithError stops streaming and sets status to error

func (*ToolBlock) ToggleExpanded 

func (tb *ToolBlock) ToggleExpanded()

ToggleExpanded toggles the expanded state

func (*ToolBlock) Update 

func (tb *ToolBlock) Update(msg tea.Msg) (Component, tea.Cmd)

Update handles messages

func (*ToolBlock) View 

func (tb *ToolBlock) View() string

View renders the tool block

type ToolBlockOption 

type ToolBlockOption func(*ToolBlock)

ToolBlockOption configures a ToolBlock

func WithLineNumbers 

func WithLineNumbers() ToolBlockOption

WithLineNumbers enables line numbers

func WithMaxLines 

func WithMaxLines(n int) ToolBlockOption

WithMaxLines sets the maximum lines to show when collapsed

func WithStatus 

func WithStatus(status ToolBlockStatus) ToolBlockOption

WithStatus sets the initial status

func WithStreaming 

func WithStreaming() ToolBlockOption

WithStreaming enables streaming mode for real-time output

func WithToolBlockDesignTokens added in v1.1.0 

func WithToolBlockDesignTokens(tokens *design.DesignTokens) ToolBlockOption

WithToolBlockDesignTokens applies design-system colors to status rendering.

func WithToolBlockTheme added in v1.1.0 

func WithToolBlockTheme(theme string) ToolBlockOption

WithToolBlockTheme applies a named design-system theme.

type ToolBlockStatus 

type ToolBlockStatus int

ToolBlockStatus represents the execution state 

const (
	StatusRunning ToolBlockStatus = iota
	StatusComplete
	StatusError
	StatusWarning
)

Source Files

View all Source files

Directories

Path Synopsis
examples
basic command
claude_code_demo command
code_demo command
codex_code_demo command
confirmation_demo command
diff_example command
fileexplorer_demo command
header_demo command
header_demo_preview command
input_demo command
kitchen_sink command
kitchen_sink_inline command
layout_demo command
modal_demo command
spinner_showcase command
streaming_demo command
structureddata_animation_demo command
structureddata_demo command
thinking_spinner_demo command
Package table provides static table rendering for CLI output.
 Package table provides static table rendering for CLI output.
example command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.