gocui README

The project's README from github.com/jroimartin/gocui. As one markdown file: README.md.

GOCUI - Go Console User Interface

Go Reference

Minimalist Go package aimed at creating Console User Interfaces.

Features

Installation

Execute:

go get github.com/jroimartin/gocui

Documentation

Execute:

go doc github.com/jroimartin/gocui

Or visit pkg.go.dev to read it online.

Example

package main

import (
	"fmt"
	"log"

	"github.com/jroimartin/gocui"
)

func main() {
	g, err := gocui.NewGui(gocui.OutputNormal)
	if err != nil {
		log.Panicln(err)
	}
	defer g.Close()

	g.SetManagerFunc(layout)

	if err := g.SetKeybinding("", gocui.KeyCtrlC, gocui.ModNone, quit); err != nil {
		log.Panicln(err)
	}

	if err := g.MainLoop(); err != nil && err != gocui.ErrQuit {
		log.Panicln(err)
	}
}

func layout(g *gocui.Gui) error {
	maxX, maxY := g.Size()
	if v, err := g.SetView("hello", maxX/2-7, maxY/2, maxX/2+7, maxY/2+2); err != nil {
		if err != gocui.ErrUnknownView {
			return err
		}
		fmt.Fprintln(v, "Hello world!")
	}
	return nil
}

func quit(g *gocui.Gui, v *gocui.View) error {
	return gocui.ErrQuit
}

Screenshots

r2cui

_examples/demo.go

_examples/dynamic.go

gocui (jroimartin/gocui)

widgets
Searching Database…

10.6K ·GitHub
What is this?Gocui is a minimalist Go package for building Console User Interfaces — text-mode apps that run in the terminal, with windows, keybindings and mouse support.
So is it a program I run, or a library I build my own app with?It's a library, not a ready-made program: you import it into your Go project and use its minimalist API to compose your own terminal UI.
How do I add it to a project?Run go get github.com/jroimartin/gocui and import it like any other Go package — nothing else to install beyond the Go toolchain. The full reference docs are on pkg.go.dev.
How does it structure a UI — what are 'views'?Views are its building blocks, the equivalent of windows in a GUI. Each view implements io.ReadWriter, so you read user input from it and write output to it like a file, and views can overlap each other.
Can apps built with it react to keyboard and mouse?Yes — keybindings can be registered globally or per view, and mouse input is supported. Rendered text can be colored, and the text editing mode is customizable.
Can I change the UI while the app is running?Yes. The GUI can be modified at runtime and this is concurrent-safe, so it stays consistent even when several parts of your program touch it at once.
How mature is gocui?It has been around since 2014 and collected over 10,000 GitHub stars, making it a long-established option for terminal UIs in Go. It is distributed under the permissive BSD-3-Clause license.
What are similar projects?wtf, BongoCat, ratatui, tui-rs, blessed, FTXUI, pyautogui, lipgloss
Creator
jroimartin
Size
0.3 MB
Stars
10.6K
Updated
CommitMay 01
Age
12y
Commits · 90 Days