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.

• 🚀 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.
  • 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 is backward compatible with termui and can mostly be used as a drop-in replacement.

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

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.

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.