gotui

A modern, high-performance Terminal User Interface (TUI) library for Go.

gotui is a fully-customizable dashboard and widget Go library built on top of tcell. It is a modernized enhanced fork of termui (v3), engineered for valid TrueColor support, high-performance rendering, flex layouts, rounded borders, input, and for feature parity with robust libraries like ratatui.

• 🚀 High Performance: optimized rendering engine capable of ~3000 FPS frame operations with zero-allocation drawing loops.
• 🎨 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.
• 📊 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.
  • Misc: TabPane, Image (block-based), Canvas (Braille), Heatmap.
• 🖱️ Mouse Support: Full mouse event support (Click, Scroll Wheel, Drag).
• 🔧 Customizable: Themes, rounded borders, border titles (alignment).

gotui uses Go modules.

go get github.com/metaspartan/gotui/v4

Requires Go Lang 1.24 or higher.

Create a main.go:

package main

import (
	"log"

	ui "github.com/metaspartan/gotui/v4"
	"github.com/metaspartan/gotui/v4/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
		}
	}
}

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
Background		View Example Code
Barchart		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
Flex		View Example Code
Funnelchart		View Example Code
Gauge		View Example Code
Grid		View Example Code
Heatmap		View Example Code
Hello World		View Example Code
Image		View Example Code
Input		View Example Code
Linechart		View Example Code
Linegauge		View Example Code
List		View Example Code
Logo		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
Stacked Barchart		View Example Code
Table		View Example Code
Tabs		View Example Code
Textarea		View Example Code
Tree		View Example Code
Treemap		View Example Code

gotui supports Rounded Borders and various 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

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
    }
}

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.

• mactop

Submit a PR to add yours here!

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

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

MIT

Original termui by Zack Guo.

Inspired by Ratatui.