README.md
December 29, 2025 · View on GitHub
gotui
A modern, high-performance Terminal User Interface (TUI) library for Go.
gotui by Carsen Klock is a fully-customizable dashboard and widget Go library built on top of tcell. It is a modernized enhanced fork of termui, engineered for valid TrueColor support, high-performance rendering, flex layouts, rounded borders, input, and for feature parity with robust libraries like ratatui.
⚡ Features
- 🚀 High Performance: optimized rendering engine capable of ~3000 FPS frame operations with zero-allocation drawing loops. (termui is ~1700 FPS)
- 🎨 TrueColor Support: Full 24-bit RGB color support for modern terminals (Ghostty, Alacritty, Kitty, iTerm2).
- 📐 Flexible Layouts:
- Flex: Mixed fixed/proportional layouts.
- Grid: 12-column dynamic grid system.
- Absolutes: Exact coordinates when needed.
- 🌐 SSH / Remote Apps: Turn any TUI into a zero-install SSH accessible application (multi-tenant support).
- 🎨 Gradient Support: Gradient support for widgets.
- 📊 Rich Widgets:
- Charts: BarChart, StackedBarChart, PieChart, DonutChart, RadarChart (Spider), FunnelChart, TreeMap, Sparkline, Plot (Scatter/Line).
- Gauges: Gauge, LineGauge (with pixel-perfect Braille/Block styles).
- Interaction: Input, TextArea, List, Table, Scrollbar, Button, Checkbox.
- Misc: TabPane, Image (block-based), Canvas (Braille), Heatmap, Logo, Spinner, Modal.
- 📱 Application API: Structured app framework with focus management, event dispatch, and auto-resize.
- 🖱️ Mouse Support: Full mouse event support (Click, Scroll Wheel, Drag).
- 🔧 Customizable: Themes, rounded borders, border titles (alignment).
🆚 Comparison
| Feature | gotui | termui |
|---|---|---|
| Renderer | tcell (Optimized) | termbox |
| Performance (FPS) | ~3300 (Heavy Load) | ~1700 |
| Widgets Available | 27+ (Calendar, Tree, Button, Checkbox...) | ~12 |
| Layout System | Flex + Grid + Absolute | Grid |
| Customization | High (Rounded Borders, Alignments) | Basic |
| Pixel-Perfect | Yes (Braille/Block/Space) | No |
| Mouse Support | Full (Wheel/Click/Drag) | Click |
| TrueColor | Yes | No |
| SSH / Multi-User | Native (Backend API) | No (Global State) |
| Modern Terminal Support | All (iterm, ghostty, etc.) | No |
gotui is backward compatible with termui and can mostly be used as a drop-in replacement.
📦 Installation
gotui uses Go modules.
go get github.com/metaspartan/gotui/v5
Requires Go Lang 1.24 or higher.
🚀 Quick Start
Create a main.go:
package main
import (
"log"
ui "github.com/metaspartan/gotui/v5"
"github.com/metaspartan/gotui/v5/widgets"
)
func main() {
if err := ui.Init(); err != nil {
log.Fatalf("failed to initialize gotui: %v", err)
}
defer ui.Close()
p := widgets.NewParagraph()
p.Title = "Hello World"
p.Text = "PRESS q TO QUIT.\n\nCombined with modern widgets, gotui aims to provide the best TUI experience in Go."
p.SetRect(0, 0, 50, 5)
p.TitleStyle.Fg = ui.ColorYellow
p.BorderStyle.Fg = ui.ColorSkyBlue
ui.Render(p)
uiEvents := ui.PollEvents()
for {
e := <-uiEvents
switch e.ID {
case "q", "<C-c>":
return
}
}
}
📚 Widgets Gallery*
Run the main dashboard demo: go run _examples/dashboard/main.go
Run individual examples: go run _examples/<name>/main.go
*Widget Screenshots are auto generated.
🛠️ Advanced Usage
Application API
For structured applications with focus management and automatic event dispatch:
package main
import (
"log"
"github.com/metaspartan/gotui/v5"
"github.com/metaspartan/gotui/v5/widgets"
)
func main() {
app := gotui.NewApp()
p := widgets.NewParagraph()
p.Title = "My App"
p.Text = "Press q or Ctrl+C to quit."
app.SetRoot(p, true) // Set root widget with focus
if err := app.Run(); err != nil {
log.Fatal(err)
}
}
The Application handles:
- Terminal initialization/cleanup
- Automatic resize handling
- Event dispatch to focused widgets
- Default quit handlers (q, Ctrl+C)
Customizing Borders
gotui supports multiple border styles and title alignments.
p.Border = true
p.BorderRounded = true // ╭───╮ instead of ┌───┐
p.Title = "My Title"
p.TitleAlignment = ui.AlignLeft // or AlignCenter, AlignRight
p.TitleBottom = "Page 1"
p.TitleBottomAlignment = ui.AlignRight
// Or use other border styles:
double := ui.BorderSetDouble()
p.BorderSet = &double // ╔═══╗
thick := ui.BorderSetThick()
p.BorderSet = &thick // ┏━━━┓
Handling Mouse Events
Events include MouseLeft, MouseRight, MouseRelease, MouseWheelUp, MouseWheelDown.
uiEvents := ui.PollEvents()
for e := range uiEvents {
if e.Type == ui.MouseEvent {
// e.ID is "MouseLeft", "MouseWheelUp", etc.
// e.Payload.X, e.Payload.Y are coordinates
}
}
🌐 Serving over SSH
You can easily serve your TUI over SSH (like standard CLI apps) using ui.InitWithConfig and a library like gliderlabs/ssh.
func sshHandler(sess ssh.Session) {
// 1. Create a custom backend for this session
app, err := ui.NewBackend(&ui.InitConfig{
CustomTTY: sess, // ssh.Session implements io.ReadWriter
})
if err != nil {
return // Handle error appropriately
}
defer app.Close()
// 2. Use the app instance instead of global ui.* functions
p := widgets.NewParagraph()
p.Text = "Hello SSH User!"
p.SetRect(0, 0, 20, 5)
app.Render(p) // Renders to the SSH client only!
}
Check _examples/ssh-dashboard for a full multi-user demo.
🤝 Contributing
Contributions are welcome! Please submit a Pull Request.
- Fork the repo.
- Create your feature branch (
git checkout -b feature/my-new-feature). - Commit your changes (
git commit -am 'Add some feature'). - Push to the branch (
git push origin feature/my-new-feature). - Create a new Pull Request.
Projects using gotui
Submit a PR to add yours here!
Author(s)
Carsen Klock (https://x.com/carsenklock)
Zack Guo (https://github.com/gizak)
License
Acknowledgments
Original termui by Zack Guo.
Inspired by Ratatui.