# tui

> tui is a terminal UI (TUI) framework for Go, built on the Elm Architecture (Model, Update, View). Module path: github.com/ows4444/tui.

A terminal UI framework for Go built on the Elm Architecture (Model / Update / View). It uses only the standard library: go.mod has no require directive, and a test in internal/archtest fails if any package imports outside the standard library and this module.

An application implements tui.Model, hands it to tui.NewProgram with the options it wants, and calls Run. The Program reads keys, mouse events and resizes, calls Update on each Msg, runs the Cmds Update returns, and redraws View with a cell diff so only changed cells are written.

Install with `go get github.com/ows4444/tui` (Go 1.25 or later). Source: https://github.com/ows4444/tui. API reference: https://pkg.go.dev/github.com/ows4444/tui. License: MIT.

## Docs

- [Overview](https://tui.nizaami.com/overview.md): Install tui with go get (Go 1.25+), write a first Model with Init, Update and View, and see every package, its stability level and the supported platforms.
- [Cookbook](https://tui.nizaami.com/cookbook.md): Short recipes. Each is copied from an Example function, which go test runs and checks against its // Output: comment, so the code compiles and the output is real.
- [Running a Program](https://tui.nizaami.com/program.md): tui.NewProgram wraps a Model in a Program, and Program.Run takes over the terminal, runs the event loop until the model quits, and restores the terminal before it returns.
- [Layout](https://tui.nizaami.com/layout.md): Lay out a Go terminal UI with layout.Node: two-pass measure and render, rows, columns, flex, grids, overlays, and how to place widgets in a layout.
- [Widgets](https://tui.nizaami.com/widgets.md): Stateless widget functions and stateful component packages for Go terminal UIs: the shared contracts, and a catalog of every component with its example program.
- [Input, key bindings, focus and mouse](https://tui.nizaami.com/input.md): The Program decodes terminal bytes with an input.Reader and passes each event to Update as a message: tui.Key, tui.MouseEvent, tui.PasteEvent, tui.FocusEvent, and the others listed below.
- [Theming](https://tui.nizaami.com/theming.md): Theme a Go terminal UI with theme.Theme: colour roles, preset themes, component tokens, glyph sets with an ASCII fallback, and colour depth.
- [Rendering](https://tui.nizaami.com/rendering.md): After each Update, the Program calls View and writes only the difference from the frame already on screen.
- [Terminal capabilities](https://tui.nizaami.com/capabilities.md): A Program learns about the terminal in two ways. At NewProgram, it reads the colour profile from the environment.
- [Accessibility](https://tui.nizaami.com/accessibility.md): tui.WithAccessible(true) switches a Program to accessible output: an append-only plain-text transcript that a screen reader can follow, with no escape sequences.
- [Testing](https://tui.nizaami.com/testing.md): Run and write tests for tui: the tuitest headless harness, golden files, PTY tests, race, fuzz and benchmark runs, and the test environment variables.
- [Examples](https://tui.nizaami.com/examples.md): Every program under examples/, with the 80×24 screen its test checks.

## Optional

- [Migrating to v1](https://tui.nizaami.com/migrating-to-v1.md): Each identifier removed before v1, and what to use instead. The - BREAKING: entries under Removed in CHANGELOG.md list the same removals.
- [Architecture overview](https://tui.nizaami.com/architecture.md): tui is a terminal UI framework on the Elm Architecture: an application is a Model with Init, Update and View, and the root package's Program turns terminal input into messages for Update and turns ...
- [Contributing](https://tui.nizaami.com/contributing.md): Most conventions here are enforced by a test or a CI job; each section names the check that fails when a rule is broken.
- [Changelog](https://tui.nizaami.com/changelog.md): User-visible changes to github.com/ows4444/tui. The format loosely follows Keep a Changelog 1.1.0.