Guide · Open source

How to use termui: install and build a Go terminal dashboard

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

termui is a Go library for building dashboards that run inside a terminal window. It ships with ready-made widgets such as charts, gauges, tables, lists and paragraphs, and you position them in a grid or at fixed coordinates. This guide shows how to add it to a Go project, run the Hello World example and understand the parts you will use.

termuigizak/termui · ★ 13.6k · MIT Install options & downloads

Quick start

1Check your Go version. Confirm you have Go 1.15 or newer installed, since that is the compatibility target in the README.
2Add termui to your project. Run go get github.com/gizak/termui/v3 inside your Go module.
3Create a main.go file. Paste the Hello World program into a new Go file in your project.
4Run the program. Start it with go run and check that the Hello World paragraph appears in your terminal.
5Add a widget. Create another widget such as a Gauge or Table, set its rectangle with SetRect and pass it to ui.Render.
6Explore the examples. Run files from the _examples folder to see each widget in action before you build your own layout.

What termui is and who it is for

termui is a cross-platform, customizable terminal dashboard and widget library written purely in Go and built on top of termbox-go. The README says it is inspired by blessed-contrib and tui-rs.

It is a library, not a finished program. You write Go code that creates the widgets and handles events, so it suits Go developers who want to build a monitoring dashboard or custom terminal widgets.

Go developers building a terminal monitoring dashboard
Programmers who need prebuilt charts, tables or gauges in a terminal app
Developers who want keyboard and mouse events handled in a text UI

Install termui in a Go project

You need Go 1.15 or newer, which the README gives as the compatibility target. With Go modules, you do not have to run go get yourself, because Go manages imported dependencies automatically when your code imports them.

The README's install command for a Go project is shown below. Keep the /v3 suffix in your import statements when using Go modules.

Prerequisite: Go 1.15 or newer
Include /v3 in import paths when using Go modules
The README also describes Dep: run dep ensure -add github.com/gizak/termui, and in that case do not include /v3 in imports

go get github.com/gizak/termui/v3

Run the Hello World example

The Hello World program initializes termui, creates a paragraph widget, sets its size and position, renders it, and waits for a keyboard event before exiting. Save it as a Go file in your project, then run it with go run.

ui.Init() starts termui and ui.Close() restores the terminal, which is why the example defers ui.Close(). The loop over ui.PollEvents() exits when a keyboard event arrives.

p.SetRect(0, 0, 25, 5) sets the paragraph's position and size
ui.Render(p) draws the widget
The program quits on the first keyboard event

package main

import (
	"log"

	ui "github.com/gizak/termui/v3"
	"github.com/gizak/termui/v3/widgets"
)

func main() {
	if err := ui.Init(); err != nil {
		log.Fatalf("failed to initialize termui: %v", err)
	}
	defer ui.Close()

	p := widgets.NewParagraph()
	p.Text = "Hello World!"
	p.SetRect(0, 0, 25, 5)

	ui.Render(p)

	for e := range ui.PollEvents() {
		if e.Type == ui.KeyboardEvent {
			break
		}
	}
}

Choose widgets for your dashboard

The README lists these widgets: BarChart, Canvas (for drawing braille dots), Gauge, Image, List, Tree, Paragraph, PieChart, Plot (for scatterplots and linecharts), Sparkline, StackedBarChart, Table and Tabs. Each has an example file in the _examples folder of the repository.

To see them working, run an example with the command below, or run all examples in sequence with make run-examples.

Charts: BarChart, PieChart, Plot, Sparkline, StackedBarChart
Status displays: Gauge, Paragraph
Data views: Table, List, Tree
Other: Canvas, Image, Tabs

go run _examples/{example}.go

Position widgets and handle events

termui lets you position widgets either in a relative grid or with absolute coordinates. The Hello World example uses absolute coordinates through SetRect.

termui also reports keyboard, mouse and terminal resizing events, and supports colors and styling. Use the wiki linked from the README for detailed API documentation.

Relative grid or absolute coordinates for placement
Keyboard, mouse and terminal resizing events
Colors and styling on widgets
Custom widgets can be created

What people use it for

A live terminal monitor showing system metrics with gauges and sparklines
A Go command-line tool that displays results in tables and lists
A tool that plots data points or line charts inside the terminal
An interactive text UI that responds to keyboard and mouse events

Frequently asked questions

How do I install termui?

In a Go project, run go get github.com/gizak/termui/v3 as shown in the README. With Go modules you do not need to run go get yourself, because Go manages imports, and you should keep /v3 in your import paths.

Is termui free to use?

termui is released under the MIT licence, as stated in the README. Check the LICENSE file in the repository for the full terms.

What version of Go does termui need?

The README states Go 1.15 or newer is the compatibility target. Teams that cannot use that version should look at other libraries.

Is termui a ready-made dashboard I can run without coding?

No. termui is a library, so you need to write Go code that creates and renders the widgets. If you want a finished program without coding, termui is not the right tool.

Is termui still maintained?

The README says update frequency may not follow a consistent schedule because of the maintainer's availability, and it invites new maintainers. Plan for irregular updates if you depend on it.

How does termui compare with termdash, tview and blessed-contrib?

The README lists blessed-contrib, tui-rs, termdash and tview as related projects, and says termui is inspired by blessed-contrib and tui-rs. termui is built on termbox-go and focuses on prebuilt dashboard widgets; compare the widget set and maintenance status of each before choosing.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

termui suits Go developers who want prebuilt charts, tables, gauges and custom widgets for a terminal dashboard and are comfortable writing code. Skip it if you want a finished dashboard program without coding, need guaranteed update schedules, or cannot use Go 1.15 or newer.

Install options & downloads