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

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.

Widget/Example	Screenshot	Code
Alignment		View Example Code
Application		View Example Code
Background		View Example Code
Barchart		View Example Code
Borders		View Example Code
Block		View Example Code
Block Multi Title		View Example Code
Calendar		View Example Code
Canvas		View Example Code
Collapsed Borders		View Example Code
Colors		View Example Code
Dashboard		View Example Code
Demo		View Example Code
Donutchart		View Example Code
Events		View Example Code
Flex		View Example Code
Funnelchart		View Example Code
Gauge		View Example Code
Gradient		View Example Code
Grid		View Example Code
Heatmap		View Example Code
Hello World		View Example Code
Image		View Example Code
Input		View Example Code
Interaction		View Example Code
Linechart		View Example Code
Linegauge		View Example Code
List		View Example Code
Logo		View Example Code
Modal		View Example Code
Modern Demo		View Example Code
Paragraph		View Example Code
Piechart		View Example Code
Plot		View Example Code
Radarchart		View Example Code
Scrollbar		View Example Code
Sparkline		View Example Code
Spinner		View Example Code
Ssh-Dashboard		View Example Code
Stacked Barchart		View Example Code
Stepchart		View Example Code
Table		View Example Code
Tabs		View Example Code
Textarea		View Example Code
Tree		View Example Code
Treemap		View Example Code

🛠️ 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.

1. Fork the repo.
2. Create your feature branch (git checkout -b feature/my-new-feature).
3. Commit your changes (git commit -am 'Add some feature').
4. Push to the branch (git push origin feature/my-new-feature).
5. Create a new Pull Request.

Projects using gotui

• mactop

Submit a PR to add yours here!

Author(s)

Carsen Klock (https://x.com/carsenklock)

Zack Guo (https://github.com/gizak)

License

MIT

Acknowledgments

Original termui by Zack Guo.

Inspired by Ratatui.