1# Rich Interactive Widgets for Terminal UIs
2
3[](https://pkg.go.dev/github.com/rivo/tview)
4[](https://goreportcard.com/report/github.com/rivo/tview)
5
6This Go package provides commonly used components for terminal based user interfaces.
7
8
9
10Among these components are:
11
12- __Input forms__ (including __text input__, __selections__, __checkboxes__, and __buttons__)
13- Navigable multi-color __text views__
14- Editable multi-line __text areas__
15- Sophisticated navigable __table views__
16- Flexible __tree views__
17- Selectable __lists__
18- __Images__
19- __Grid__, __Flexbox__ and __page layouts__
20- Modal __message windows__
21- An __application__ wrapper
22
23They come with lots of customization options and can be easily extended to fit your needs.
24
25## Usage
26
27To add this package to your project:
28
29```bash
30go get github.com/rivo/tview
31```
32
33## Hello World
34
35This basic example creates a box titled "Hello, World!" and displays it in your terminal:
36
37```go
38package main
39
40import (
41 "github.com/rivo/tview"
42)
43
44func main() {
45 box := tview.NewBox().SetBorder(true).SetTitle("Hello, world!")
46 if err := tview.NewApplication().SetRoot(box, true).Run(); err != nil {
47 panic(err)
48 }
49}
50```
51
52Check out the [GitHub Wiki](https://github.com/rivo/tview/wiki) for more examples along with screenshots. Or try the examples in the "demos" subdirectory.
53
54For a presentation highlighting this package, compile and run the program found in the "demos/presentation" subdirectory.
55
56## Projects using `tview`
57
58- [K9s - Kubernetes CLI](https://github.com/derailed/k9s)
59- [IRCCloud Terminal Client](https://github.com/termoose/irccloud)
60- [Window manager for `tview`](https://github.com/epiclabs-io/winman)
61- [CLI bookmark manager](https://github.com/Endi1/drawer)
62- [A caving database interface written in Go](https://github.com/IdlePhysicist/cave-logger)
63- [Interactive file browse and exec any command.](https://github.com/bannzai/itree)
64- [A simple CRM](https://github.com/broadcastle/crm)
65- [Terminal UI for todist](https://github.com/cyberdummy/todoista)
66- [Graphical kubectl wrapper](https://github.com/dcaiafa/kpick)
67- [Decred Decentralized Exchange ](https://github.com/decred/dcrdex)
68- [A CLI file browser for Raspberry PI](https://github.com/destinmoulton/pixi)
69- [A tool to manage projects.](https://github.com/divramod/dp)
70- [A simple app for BMI monitoring](https://github.com/erleene/go-bmi)
71- [Stream TIDAL from command line](https://github.com/godsic/vibe)
72- [Secure solution for fully decentralized password management](https://github.com/guillaumemichel/passtor/)
73- [A growing collection of convenient little tools to work with systemd services](https://github.com/muesli/service-tools/)
74- [A terminal based browser for Redis written in Go](https://github.com/nitishm/redis-terminal)
75- [First project for the Computer Networks course.](https://github.com/pablogadhi/XMPPClient)
76- [Test your typing speed in the terminal!](https://github.com/shilangyu/typer-go)
77- [TUI Client for Docker](https://github.com/skanehira/docui)
78- [SSH client using certificates signed by HashiCorp Vault](https://github.com/stephane-martin/vssh)
79- [A go terminal based pos software.](https://github.com/thebmw/y2kpos)
80- [VMware vCenter Text UI](https://github.com/thebsdbox/vctui)
81- [Bookmarks on terminal](https://github.com/tryffel/bookmarker)
82- [A UDP testing utility](https://github.com/vaelen/udp-tester)
83- [A simple Kanban board for your terminal](https://github.com/witchard/toukan)
84- [The personal information dashboard for your terminal. ](https://github.com/wtfutil/wtf)
85- [MySQL database to Golang struct](https://github.com/xxjwxc/gormt)
86- [Discord, TUI and SIXEL.](https://gitlab.com/diamondburned/6cord)
87- [A CLI Audio Player](https://www.github.com/dhulihan/grump)
88- [GLab, a GitLab CLI tool](https://gitlab.com/profclems/glab)
89- [Browse your AWS ECS Clusters in the Terminal](https://github.com/swartzrock/ecsview)
90- [The CLI Task Manager for Geeks](https://github.com/ajaxray/geek-life)
91- [Fast disk usage analyzer written in Go](https://github.com/dundee/gdu)
92- [Multiplayer Chess On Terminal](https://github.com/qnkhuat/gochess)
93- [Scriptable TUI music player](https://github.com/issadarkthing/gomu)
94- [MangaDesk : TUI Client for downloading manga to your computer](https://github.com/darylhjd/mangadesk)
95- [Go How Much? a Crypto coin price tracking from terminal](https://github.com/ledongthuc/gohowmuch)
96- [dbui: Universal CLI for Database Connections](https://github.com/KenanBek/dbui)
97- [ssmbrowse: Simple and elegant cli AWS SSM parameter browser](https://github.com/bnaydenov/ssmbrowse)
98- [gobit: binance intelligence terminal](https://github.com/infl00p/gobit)
99- [viddy: A modern watch command](https://github.com/sachaos/viddy)
100- [s3surfer: CLI tool for browsing S3 bucket and download objects interactively](https://github.com/hirose31/s3surfer)
101- [libgen-tui: A terminal UI for downloading books from Library Genesis](https://github.com/audstanley/libgen-tui)
102- [kubectl-lazy: kubectl plugin to easy to view pod](https://github.com/togettoyou/kubectl-lazy)
103- [podman-tui: podman user interface](https://github.com/containers/podman-tui)
104- [tvxwidgets: tview extra widgets](https://github.com/navidys/tvxwidgets)
105- [Domino card game on terminal](https://github.com/gusti-andika/card-domino.git)
106- [goaround: Query stackoverflow API and get results on terminal](https://github.com/glendsoza/goaround)
107- [resto: a CLI app can send pretty HTTP & API requests with TUI](https://github.com/abdfnx/resto)
108- [twad: a WAD launcher for the terminal](https://github.com/zmnpl/twad)
109- [pacseek: A TUI for searching and installing Arch Linux packages](https://github.com/moson-mo/pacseek)
110- [7GUIs demo](https://github.com/letientai299/7guis/tree/master/tui)
111- [tuihub: A utility hub/dashboard for personal use](https://github.com/ashis0013/tuihub)
112- [l'oggo: A terminal app for structured log streaming (GCP stack driver, k8s, local streaming)](https://github.com/aurc/loggo)
113- [reminder: Terminal based interactive app for organising tasks with minimal efforts.](https://github.com/goyalmunish/reminder)
114- [tufw: A terminal UI for ufw.](https://github.com/peltho/tufw)
115- [gh: the GitHub CLI](https://github.com/cli/cli)
116- [piptui: Terminal UI to manage pip packages](https://github.com/glendsoza/piptui/)
117- [cross-clipboard: A cross-platform clipboard sharing](https://github.com/ntsd/cross-clipboard)
118- [tui-deck: nextcloud deck frontend](https://github.com/mebitek/tui-deck)
119- [ktop: A top-like tool for your Kubernetes clusters](https://github.com/vladimirvivien/ktop)
120
121## Documentation
122
123Refer to https://pkg.go.dev/github.com/rivo/tview for the package's documentation. Also check out the [Wiki](https://github.com/rivo/tview/wiki).
124
125## Dependencies
126
127This package is based on [github.com/gdamore/tcell](https://github.com/gdamore/tcell) (and its dependencies) as well as on [github.com/rivo/uniseg](https://github.com/rivo/uniseg).
128
129## Sponsor this Project
130
131[Become a Sponsor on GitHub](https://github.com/sponsors/rivo?metadata_source=tview_readme) to further this project!
132
133## Versioning and Backwards-Compatibility
134
135I try really hard to keep this project backwards compatible. Your software should not break when you upgrade `tview`. But this also means that some of its shortcomings that were present in the initial versions will remain. In addition, at least for the time being, you won't find any version tags in this repo. The newest version should be the one to upgrade to. It has all the bugfixes and latest features. Having said that, backwards compatibility may still break when:
136
137- a new version of an imported package (most likely [`tcell`](https://github.com/gdamore/tcell)) changes in such a way that forces me to make changes in `tview` as well,
138- I fix something that I consider a bug, rather than a feature, something that does not work as originally intended,
139- I make changes to "internal" interfaces such as [`Primitive`](https://pkg.go.dev/github.com/rivo/tview#Primitive). You shouldn't need these interfaces unless you're writing your own primitives for `tview`. (Yes, I realize these are public interfaces. This has advantages as well as disadvantages. For the time being, it is what it is.)
140
141## Your Feedback
142
143Add your issue here on GitHub. Feel free to get in touch if you have any questions.
144
145## Code of Conduct
146
147We follow Golang's Code of Conduct which you can find [here](https://golang.org/conduct).
View as plain text