termkit-go

README

termkit-go

The demo is a live Bubble Tea dashboard: use 1–5 to switch chart types, ←/→ (or h/l) to move the selection, tab to switch series, and q to quit.

Run go run ./cmd/demo --dither-kit for a static terminal comparison sheet covering the avatar, button states, gradient wash, and decorative sparkline.

Terminal charts, motion, and UI components for Go CLIs and TUIs. The chart palette and texture are inspired by Dither Kit.

Install

go get github.com/pol-cova/termkit-go

Packages

Package	Includes	API
chart	Area, line, bar, pie, radar; stacked and percent modes; interactive selection.	docs · Go reference
animate	Tween, spring, pulse, repeat, and easing helpers.	docs · Go reference
component	Panels, inputs, selects, tabs, tables, sparklines, breadcrumbs, progress, gauges, spinners, badges, cards, dividers, status bars, dither-kit buttons, avatars, and gradient washes.	docs · Go reference
sound	Optional interaction cues through the terminal bell or your own player.	Go reference

Each package returns values or strings. It does not own your event loop, terminal, or rendering framework.

Quick start

import (
    "fmt"

    "github.com/pol-cova/termkit-go/chart"
)

plot := chart.Chart{
    Kind: chart.Area,
    Labels: []string{"Jan", "Feb", "Mar", "Apr"},
    StackType: chart.Stacked,
    Series: []chart.Series{
        {Name: "desktop", Values: []float64{120, 190, 230, 210}, Variant: chart.Dotted},
        {Name: "mobile", Values: []float64{80, 120, 140, 110}, Variant: chart.Hatched},
    },
}

view, err := chart.Render(plot, chart.Options{Width: 56, Height: 12, Selected: 2, Color: true})
if err != nil { panic(err) }
fmt.Println(view)

Bubble Tea

Keep selection in your model and render the view from View:

view, err := chart.Render(plot, chart.Options{
    Width:        m.width,
    Height:       10,
    Selected:     m.selected,
    ActiveSeries: m.activeSeries,
    Color:        true,
})
if err != nil { return err.Error() }
return view

Update m.selected from arrow keys, j/k, or mouse input. See the interactive demo for the complete model.

Motion and status components

import (
    "fmt"

    "github.com/pol-cova/termkit-go/animate"
    "github.com/pol-cova/termkit-go/component"
)

progress := animate.Tween(0.65, animate.EaseInOut)
fmt.Println(component.Progress("Deploy", progress, 20, component.Accent))
fmt.Println(component.SpinnerFrame(frame, "Connecting", component.Warning))

Interactive building blocks

The component package stays event-loop neutral, but includes the primitives needed to build a small OpenTUI-style app:

input := component.Input{Placeholder: "Search…", MaxLength: 80}
input.HandleKey("hello")
menu := component.Select{Options: []component.Option{{Label: "Dashboard"}, {Label: "Settings"}}, Height: 4}
menu.HandleKey("down")
fmt.Println(component.Panel("Command palette", input.View(true, component.Accent), 36, component.Accent))
fmt.Println(menu.View(32, component.Accent))

Sound is opt-in and has no platform dependency. sound.Bell emits the terminal's native cue; applications can implement sound.Player to synthesize or route cues elsewhere.

import (
    "os"

    "github.com/pol-cova/termkit-go/sound"
)

player := sound.Bell{Out: os.Stdout}
player.Play(sound.Success)

Demo

go run ./cmd/demo

Use 1–5 to change chart type, ←/→ (or h/l) to scrub, tab to switch series, and q to quit.

Requirements

Go 1.24 or newer. The library itself has no required UI framework; the demo uses Bubble Tea.

Docs

• Charts and visual variants — chart types, stacking, selection, and rendering options
• Motion and components — animation, panels, inputs, selects, tables, and interaction cues
• Dither Kit fidelity map — reference component mapping and ported visual constants
• Interactive demo source · VHS recording script · GIF preview
• Go API: chart · component · sound
• Contributing

Development

go test ./...
go vet ./...
vhs demo.tape

MIT licensed. See LICENSE.