termdash

package module

v0.22.0 Latest Latest Go to latest Published: Jun 9, 2026 License: Apache-2.0 Imports: 8 Imported by: 123

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/mum4k/termdash

Links

Open Source Insights

README ¶

Termdash is a cross-platform customizable terminal based dashboard.

The feature set is inspired by the gizak/termui project, which in turn was inspired by yaronn/blessed-contrib.

This rewrite focuses on code readability, maintainability and testability, see the design goals. It aims to achieve the following requirements. See the high-level design for more details.

Public API and status

The public API surface is documented in the wiki.

Private packages can be identified by the presence of the /private/ directory in their import path. Stability of the private packages isn't guaranteed and changes won't be backward compatible.

There might still be breaking changes to the public API, at least until the project reaches version 1.0.0. Any breaking changes will be published in the changelog.

Current feature set

Full support for terminal window resizing throughout the infrastructure.
Customizable layout, widget placement, borders, margins, padding, colors, etc.
Dynamic layout changes at runtime.
Binary tree and Grid forms of setting up the layout.
Focusable containers and widgets.
Processing of keyboard and mouse events.
Periodic and event driven screen redraw.
A library of widgets, see below.
UTF-8 for all text elements.
Drawing primitives (Go functions) for widget development with character and sub-character resolution.

Installation

To install this library, run the following:

go get -u github.com/mum4k/termdash
cd github.com/mum4k/termdash

Usage

The usage of most of these elements is demonstrated in termdashdemo.go. To execute the demo:

go run termdashdemo/termdashdemo.go

Documentation

Please refer to the Termdash wiki for all documentation and resources.

Implemented Widgets

The Button

Allows users to interact with the application, each button press runs a callback function. Run the buttondemo.

go run widgets/button/buttondemo/buttondemo.go

The TextInput

Allows users to interact with the application by entering, editing and submitting text data. Run the textinputdemo.

go run widgets/textinput/textinputdemo/textinputdemo.go

Can be used to create text input forms that support keyboard navigation:

go run widgets/textinput/formdemo/formdemo.go

The Gauge

Displays the progress of an operation. Run the gaugedemo.

go run widgets/gauge/gaugedemo/gaugedemo.go

The Pie

Visualizes series of values as pie slices in the pie chart. Run the pie demo.

go run widgets/pie/piedemo/piedemo.go

The Donut

Visualizes progress of an operation as a partial or a complete donut. Run the donutdemo.

go run widgets/donut/donutdemo/donutdemo.go

The Text

Displays text content, supports trimming and scrolling of content. Run the textdemo.

go run widgets/text/textdemo/textdemo.go

The SparkLine

Draws a graph showing a series of values as vertical bars. The bars can have sub-cell height. Run the sparklinedemo.

go run widgets/sparkline/sparklinedemo/sparklinedemo.go

The BarChart

Displays multiple bars showing relative ratios of values. Run the barchartdemo.

go run widgets/barchart/barchartdemo/barchartdemo.go

The LineChart

Displays series of values on a line chart, supports zoom triggered by mouse events. Run the linechartdemo.

go run widgets/linechart/linechartdemo/linechartdemo.go

The SegmentDisplay

Displays text by simulating a 16-segment display. Run the segmentdisplaydemo.

go run widgets/segmentdisplay/segmentdisplaydemo/segmentdisplaydemo.go

The TreeView

Displays a tree view which provides a hierarchical and collapsible view for displaying and interacting with nested data structures. treeviewdemo.

go run widgets/treeview/treeviewdemo/treeviewdemo.go

The Checkbox

Allows users to toggle a single boolean value. Run the checkboxdemo.

go run widgets/checkbox/checkboxdemo/checkboxdemo.go

Allows users to select one value from a fixed list of items. Run the dropdowndemo.

go run widgets/dropdown/dropdowndemo/dropdowndemo.go

The Radio

Allows users to select one item from a group of radio options. Run the radiodemo.

go run widgets/radio/radiodemo/radiodemo.go

The Slider

Allows users to choose a numeric value from a bounded range. Run the sliderdemo.

go run widgets/slider/sliderdemo/sliderdemo.go

The Tab

Displays tabbed interfaces with keyboard and mouse navigation, notifications and dynamically updated content. Run the tabdemo.

go run widgets/tab/tabdemo/tabdemo.go

Displays modal overlays that can host and move draggable child widgets. Run the modaldemo.

go run widgets/modal/modaldemo/modaldemo.go

The Timeline

Displays a scrollable event log with severity markers and time range filtering. Run the timelinedemo.

go run widgets/timeline/timelinedemo/timelinedemo.go

The HeatMap

Displays heat maps with labeled axes and configurable cell colors. Run the heatmapdemo.

go run widgets/heatmap/heatmapdemo/heatmapdemo.go

The Spectrum

Displays audio-style spectrum analyzer data with configurable bars, colors and threshold controls. Run the spectrumdemo.

go run widgets/spectrum/spectrumdemo/spectrumdemo.go

The Radar

Displays an animated radar sweep with contacts and range rings. Run the radardemo.

go run widgets/radar/radardemo/radardemo.go

The ThreeD

Displays rotating 3D models, symbols and image-derived glyphs in the terminal. Run the threeddemo.

go run widgets/threed/threeddemo/threeddemo.go

The FX

Wraps widgets with animated effects such as fade, sweep, scramble and framed canvas rendering. Run the fxdemo.

go run widgets/fx/fxdemo/fxdemo.go

The BorderFX

Provides animated border and title effects for containers. Run the borderfxdemo.

go run widgets/borderfx/borderfxdemo/borderfxdemo.go

The Toast

Displays configurable toast notifications in normal containers and modal windows, with placement, animation, progress and action callbacks. Run the toastdemo.

go run widgets/toast/toastdemo/toastdemo.go

The HUD

Displays a drop-down modal HUD overlay with live OS values, compact in/out sparklines, a disk pie, a 3D spectrum analyzer, a telemetry treeview, double-Escape toggling, animated borderfx framing, embedded toast notifications and action controls. Run the huddemo.

go run widgets/hud/huddemo/huddemo.go

The EmojiKeyboard

Displays a paginated emoji grid for keyboard and mouse selection. It is demonstrated in the tabdemo.

go run widgets/tab/tabdemo/tabdemo.go

Contributing

If you are willing to contribute, improve the infrastructure or develop a widget, first of all Thank You! Your help is appreciated.

Please see the CONTRIBUTING.md file for guidelines related to the Google's CLA, and code review requirements.

As stated above the primary goal of this project is to develop readable, well designed code, the functionality and efficiency come second. This is achieved through detailed code reviews, design discussions and following of the design guidelines. Please familiarize yourself with these before contributing.

If you're developing a new widget, please see the widget development section.

Termdash uses this branching model. When you fork the repository, base your changes off the devel branch and the pull request should merge it back to the devel branch. Commits to the master branch are limited to releases, major bug fixes and documentation updates.

Similar projects in Go

Projects using Termdash

datadash: Visualize streaming or tabular data inside the terminal.
grafterm: Metrics dashboards visualization on the terminal.
perfstat: Analyze and show tips about possible bottlenecks in Linux systems.
gex: Cosmos SDK explorer in-terminal.
ali: ALI HTTP load testing tool with realtime analysis.
suimon: SUI blockchain explorer and monitor.

Disclaimer

This is not an official Google product.

Documentation ¶

Overview ¶

Package termdash implements a terminal based dashboard.

While running, the terminal dashboard performs the following:

Periodic redrawing of the canvas and all the widgets.
Event based redrawing of the widgets (i.e. on Keyboard or Mouse events).
Forwards input events to widgets and optional subscribers.
Handles terminal resize events.

Example ¶

Example shows how to setup and run termdash with periodic redraw.

// Create the terminal.
t, err := tcell.New()
if err != nil {
	panic(err)
}
defer t.Close()

// Create some widgets.
bc, err := barchart.New()
if err != nil {
	panic(err)
}
g, err := gauge.New()
if err != nil {
	panic(err)
}

// Create the container with two widgets.
c, err := container.New(
	t,
	container.SplitVertical(
		container.Left(
			container.PlaceWidget(bc),
		),
		container.Right(
			container.PlaceWidget(g),
		),
		container.SplitPercent(30),
	),
)
if err != nil {
	panic(err)
}

// Termdash runs until the context expires.
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
if err := Run(ctx, t, c); err != nil {
	panic(err)
}

Example (Triggered) ¶

Example shows how to setup and run termdash with manually triggered redraw.

// Create the terminal.
t, err := tcell.New()
if err != nil {
	panic(err)
}
defer t.Close()

// Create a widget.
bc, err := barchart.New()
if err != nil {
	panic(err)
}

// Create the container with a widget.
c, err := container.New(
	t,
	container.PlaceWidget(bc),
)
if err != nil {
	panic(err)
}

// Create the controller and disable periodic redraw.
ctrl, err := NewController(t, c)
if err != nil {
	panic(err)
}
// Close the controller and termdash once it isn't required anymore.
defer ctrl.Close()

// Redraw the terminal manually.
if err := ctrl.Redraw(); err != nil {
	panic(err)
}

Index ¶

Constants
func Run(ctx context.Context, t terminalapi.Terminal, c *container.Container, ...) error
type Controller
- func NewController(t terminalapi.Terminal, c *container.Container, opts ...Option) (*Controller, error)
- func (c *Controller) Close()
- func (c *Controller) Redraw() error
type Option

Constants ¶

View Source

const DefaultRedrawInterval = 250 * time.Millisecond

DefaultRedrawInterval is the default for the RedrawInterval option.

Variables ¶

This section is empty.

Functions ¶

func Run ¶

func Run(ctx context.Context, t terminalapi.Terminal, c *container.Container, opts ...Option) error

Run runs the terminal dashboard with the provided container on the terminal. Redraws the terminal periodically. If you prefer a manual redraw, use the Controller instead. Blocks until the context expires.

Types ¶

type Controller ¶ added in v0.2.0

type Controller struct {
	// contains filtered or unexported fields
}

Controller controls a termdash instance. The controller instance is only valid until Close() is called. The controller is not thread-safe.

func NewController ¶ added in v0.2.0

func NewController(t terminalapi.Terminal, c *container.Container, opts ...Option) (*Controller, error)

NewController initializes termdash and returns an instance of the controller. Periodic redrawing is disabled when using the controller, the RedrawInterval option is ignored. Close the controller when it isn't needed anymore.

func (*Controller) Close ¶ added in v0.2.0

func (c *Controller) Close()

Close closes the Controller and its termdash instance.

func (*Controller) Redraw ¶ added in v0.2.0

func (c *Controller) Redraw() error

Redraw triggers redraw of the terminal.

type Option ¶

type Option interface {
	// contains filtered or unexported methods
}

Option is used to provide options.

func ErrorHandler ¶

func ErrorHandler(f func(error)) Option

ErrorHandler is used to provide a function that will be called with all errors that occur while the dashboard is running. If not provided, any errors panic the application. The provided function must be thread-safe.

func KeyboardSubscriber ¶

func KeyboardSubscriber(f func(*terminalapi.Keyboard)) Option

KeyboardSubscriber registers a subscriber for Keyboard events. Each keyboard event is forwarded to the container and the registered subscriber. The provided function must be thread-safe.

func MouseSubscriber ¶

func MouseSubscriber(f func(*terminalapi.Mouse)) Option

MouseSubscriber registers a subscriber for Mouse events. Each mouse event is forwarded to the container and the registered subscriber. The provided function must be thread-safe.

func RedrawInterval ¶

func RedrawInterval(t time.Duration) Option

RedrawInterval sets how often termdash redraws the container and all the widgets. Defaults to DefaultRedrawInterval. Use the controller to disable the periodic redraw.

Source Files ¶

View all Source files

termdash.go

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
align Package align defines constants representing types of alignment.	Package align defines constants representing types of alignment.
cell Package cell implements cell options and attributes.	Package cell implements cell options and attributes.
container Package container defines a type that wraps other containers or widgets.	Package container defines a type that wraps other containers or widgets.
grid Package grid helps to build grid layouts.	Package grid helps to build grid layouts.
keyboard Package keyboard defines well known keyboard keys and shortcuts.	Package keyboard defines well known keyboard keys and shortcuts.
linestyle Package linestyle defines various line styles.	Package linestyle defines various line styles.
mouse Package mouse defines known mouse buttons.	Package mouse defines known mouse buttons.
private
alignfor Package alignfor provides functions that align elements.	Package alignfor provides functions that align elements.
area Package area provides functions working with image areas.	Package area provides functions working with image areas.
attrrange Package attrrange simplifies tracking of attributes that apply to a range of items.	Package attrrange simplifies tracking of attributes that apply to a range of items.
button Package button implements a state machine that tracks mouse button clicks.	Package button implements a state machine that tracks mouse button clicks.
canvas Package canvas defines the canvas that the widgets draw on.	Package canvas defines the canvas that the widgets draw on.
canvas/braille Package braille provides a canvas that uses braille characters.	Package braille provides a canvas that uses braille characters.
canvas/braille/testbraille Package testbraille provides helpers for tests that use the braille package.	Package testbraille provides helpers for tests that use the braille package.
canvas/buffer Package buffer implements a 2-D buffer of cells.	Package buffer implements a 2-D buffer of cells.
canvas/testcanvas Package testcanvas provides helpers for tests that use the canvas package.	Package testcanvas provides helpers for tests that use the canvas package.
draw Package draw provides functions that draw lines, shapes, etc on 2-D terminal like canvases.	Package draw provides functions that draw lines, shapes, etc on 2-D terminal like canvases.
draw/testdraw Package testdraw provides helpers for tests that use the draw package.	Package testdraw provides helpers for tests that use the draw package.
event Package event provides a non-blocking event distribution and subscription system.	Package event provides a non-blocking event distribution and subscription system.
event/eventqueue Package eventqueue provides an unboud FIFO queue of events.	Package eventqueue provides an unboud FIFO queue of events.
event/testevent Package testevent provides utilities for tests that deal with concurrent events.	Package testevent provides utilities for tests that deal with concurrent events.
faketerm Package faketerm is a fake implementation of the terminal for the use in tests.	Package faketerm is a fake implementation of the terminal for the use in tests.
fakewidget Package fakewidget implements a fake widget that is useful for testing the termdash infrastructure.	Package fakewidget implements a fake widget that is useful for testing the termdash infrastructure.
numbers Package numbers implements various numerical functions.	Package numbers implements various numerical functions.
numbers/trig Package trig implements various trigonometrical calculations.	Package trig implements various trigonometrical calculations.
runewidth Package runewidth is a wrapper over github.com/mattn/go-runewidth which gives different treatment to certain runes with ambiguous width.	Package runewidth is a wrapper over github.com/mattn/go-runewidth which gives different treatment to certain runes with ambiguous width.
segdisp Package segdisp provides utilities used by all segment display types.	Package segdisp provides utilities used by all segment display types.
segdisp/dotseg Package dotseg simulates a segment display that can draw dots.	Package dotseg simulates a segment display that can draw dots.
segdisp/dotseg/testdotseg Package testdotseg provides helpers for tests that use the dotseg package.	Package testdotseg provides helpers for tests that use the dotseg package.
segdisp/segment Package segment provides functions that draw a single segment.	Package segment provides functions that draw a single segment.
segdisp/segment/testsegment Package testsegment provides helpers for tests that use the segment package.	Package testsegment provides helpers for tests that use the segment package.
segdisp/sixteen Package sixteen simulates a 16-segment display drawn on a canvas.	Package sixteen simulates a 16-segment display drawn on a canvas.
segdisp/sixteen/testsixteen Package testsixteen provides helpers for tests that use the sixteen package.	Package testsixteen provides helpers for tests that use the sixteen package.
wrap Package wrap implements line wrapping at character or word boundaries.	Package wrap implements line wrapping at character or word boundaries.
termdashdemo Binary termdashdemo showcases every termdash widget across themed tabs.	Binary termdashdemo showcases every termdash widget across themed tabs.
terminal
tcell
termbox Package termbox implements terminal using the nsf/termbox-go library.	Package termbox implements terminal using the nsf/termbox-go library.
terminalapi Package terminalapi defines the API of all terminal implementations.	Package terminalapi defines the API of all terminal implementations.
widgetapi Package widgetapi defines the API of a widget on the dashboard.	Package widgetapi defines the API of a widget on the dashboard.
widgets
barchart Package barchart implements a widget that draws multiple bars displaying values and their relative ratios.	Package barchart implements a widget that draws multiple bars displaying values and their relative ratios.
barchart/barchartdemo command Binary barchartdemo displays a couple of BarChart widgets.	Binary barchartdemo displays a couple of BarChart widgets.
borderfx Package borderfx provides animated border effects for Termdash containers.	Package borderfx provides animated border effects for Termdash containers.
borderfx/borderfxdemo command Binary borderfxdemo - animated LCARS-style borders.	Binary borderfxdemo - animated LCARS-style borders.
button Package button implements an interactive widget that can be pressed to activate.	Package button implements an interactive widget that can be pressed to activate.
button/buttondemo command Binary buttondemo shows the functionality of a button widget.	Binary buttondemo shows the functionality of a button widget.
checkbox Package checkbox implements an interactive checkbox widget.	Package checkbox implements an interactive checkbox widget.
checkbox/checkboxdemo command Binary checkboxdemo shows the functionality of a checkbox widget.	Binary checkboxdemo shows the functionality of a checkbox widget.
donut Package donut is a widget that displays the progress of an operation as a partial or full circle.	Package donut is a widget that displays the progress of an operation as a partial or full circle.
donut/donutdemo command Binary donutdemo displays a couple of Donut widgets.	Binary donutdemo displays a couple of Donut widgets.
dropdown Package dropdown implements an interactive dropdown selection widget.	Package dropdown implements an interactive dropdown selection widget.
dropdown/dropdowndemo command Binary dropdowndemo shows the functionality of a dropdown widget.	Binary dropdowndemo shows the functionality of a dropdown widget.
fx Package fx provides a composable, time-driven cell-level effect pipeline for termdash widgets.	Package fx provides a composable, time-driven cell-level effect pipeline for termdash widgets.
fx/fxdemo command Binary fxdemo showcases every built-in effect in the widgets/fx package.	Binary fxdemo showcases every built-in effect in the widgets/fx package.
gauge Package gauge implements a widget that displays the progress of an operation.	Package gauge implements a widget that displays the progress of an operation.
gauge/gaugedemo command Binary gaugedemo displays a couple of Gauge widgets.	Binary gaugedemo displays a couple of Gauge widgets.
heatmap Package heatmap contains a widget that displays heat maps.	Package heatmap contains a widget that displays heat maps.
heatmap/heatmapdemo command Binary heatmapdemo displays a heatmap widget.	Binary heatmapdemo displays a heatmap widget.
heatmap/internal/axes Package axes calculates the required layout and draws the X and Y axes of a heat map.	Package axes calculates the required layout and draws the X and Y axes of a heat map.
linechart Package linechart contains a widget that displays line charts.	Package linechart contains a widget that displays line charts.
linechart/internal/axes Package axes calculates the required layout and draws the X and Y axes of a line chart.	Package axes calculates the required layout and draws the X and Y axes of a line chart.
linechart/internal/zoom Package zoom contains code that tracks the current zoom level.	Package zoom contains code that tracks the current zoom level.
linechart/linechartdemo command Binary linechartdemo displays a linechart widget.	Binary linechartdemo displays a linechart widget.
modal
modal/modaldemo command Binary modaldemo shows draggable widgets hosted inside a modal.	Binary modaldemo shows draggable widgets hosted inside a modal.
pie
pie/piedemo command
radar Package radar is a widget that renders an animated radar sweep display.	Package radar is a widget that renders an animated radar sweep display.
radar/radardemo command Binary radardemo displays a live radar sweep with randomly generated contacts and a real-time contact log.	Binary radardemo displays a live radar sweep with randomly generated contacts and a real-time contact log.
radio Package radio implements an interactive radio button group widget.	Package radio implements an interactive radio button group widget.
radio/radiodemo command Binary radiodemo shows the functionality of a radio widget.	Binary radiodemo shows the functionality of a radio widget.
segmentdisplay Package segmentdisplay is a widget that displays text by simulating a segment display.	Package segmentdisplay is a widget that displays text by simulating a segment display.
segmentdisplay/segmentdisplaydemo command Binary segmentdisplaydemo shows the functionality of a segment display.	Binary segmentdisplaydemo shows the functionality of a segment display.
slider Package slider implements an interactive value slider widget.	Package slider implements an interactive value slider widget.
slider/sliderdemo command Binary sliderdemo shows the functionality of a slider widget.	Binary sliderdemo shows the functionality of a slider widget.
sparkline Package sparkline is a widget that draws a graph showing a series of values as vertical bars.	Package sparkline is a widget that draws a graph showing a series of values as vertical bars.
sparkline/sparklinedemo command Binary sparklinedemo displays a couple of SparkLine widgets.	Binary sparklinedemo displays a couple of SparkLine widgets.
spectrum Package spectrum implements an audio-style spectrum analyzer widget.	Package spectrum implements an audio-style spectrum analyzer widget.
spectrum/spectrumdemo command Binary spectrumdemo shows the functionality of a spectrum widget.	Binary spectrumdemo shows the functionality of a spectrum widget.
spinner Package spinner exposes reusable UTF-8 spinner frame sets sourced from github.com/kojix2/spinner2.	Package spinner exposes reusable UTF-8 spinner frame sets sourced from github.com/kojix2/spinner2.
tab Package tab provides configuration options for the tabbed interface.	Package tab provides configuration options for the tabbed interface.
tab/tabdemo command Binary tabdemo shows the tab widget in a unified multi-widget dashboard.	Binary tabdemo shows the tab widget in a unified multi-widget dashboard.
text Package text contains a widget that displays textual data.	Package text contains a widget that displays textual data.
text/textdemo command Binary textdemo displays a couple of Text widgets.	Binary textdemo displays a couple of Text widgets.
textinput Package textinput implements a widget that accepts text input.	Package textinput implements a widget that accepts text input.
textinput/formdemo command Binary formdemo creates a form that accepts text inputs and supports keyboard navigation.	Binary formdemo creates a form that accepts text inputs and supports keyboard navigation.
textinput/textinputdemo command Binary textinputdemo shows the functionality of a text input field.	Binary textinputdemo shows the functionality of a text input field.
threed Package threed renders simple 3D models in a Termdash widget.	Package threed renders simple 3D models in a Termdash widget.
threed/threeddemo command Binary threeddemo shows the threed widget as a polished multi-scene showcase.	Binary threeddemo shows the threed widget as a polished multi-scene showcase.
timeline Package timeline provides a scrollable event-log widget for termdash.	Package timeline provides a scrollable event-log widget for termdash.
timeline/timelinedemo command Package main is the ops-dashboard demo for the timeline widget.	Package main is the ops-dashboard demo for the timeline widget.
toast Package toast provides animated notification stacks.	Package toast provides animated notification stacks.
toast/toastdemo command Binary toastdemo shows animated toast notifications in normal containers and modal windows.	Binary toastdemo shows animated toast notifications in normal containers and modal windows.
treeview
treeview/treeviewdemo command treeviewdemo.go	treeviewdemo.go