TUI — Terminal User Interface Framework for Go on TUI

Component

Mon, 01 Jan 0001 00:00:00 +0000

Component is the core interface for TUI applications.

Interface

 go
 
 
type Component interface {
 Init() Cmd
 Update(msg Msg) (Component, Cmd)
 Render(buf *Buffer, area Rect)
}

Init

 go
 
func Init() Cmd

Called once when the application starts. Return a Cmd to run an initial command (start a timer, fetch data), or nil for no initial action.

Update

 go
 
func Update(msg Msg) (Component, Cmd)

Called when a message arrives (key press, mouse event, timer tick, custom message). Update state and return the component and an optional command. Return a different Component to swap the root component entirely.

Hello World

Mon, 01 Jan 0001 00:00:00 +0000

Minimal Application

The simplest TUI application renders text and quits on Ctrl+C:

 go
 
 
package main

import (
 "log"
 "tui"
)

type app struct{}

func (a *app) Init() tui.Cmd { return nil }
func (a *app) Update(msg tui.Msg) (tui.Component, tui.Cmd) {
 if msg, ok := msg.(tui.KeyMsg); ok && msg.Type == tui.KeyCtrlC {
 return a, tui.QuitCmd()
 }
 return a, nil
}
func (a *app) Render(buf *tui.Buffer, area tui.Rect) {
 buf.SetString(0, 0, "Hello, World!", tui.NewStyle().Fg(tui.Green).Bold(true))
}

func main() {
 if err := tui.Run(&app{}); err != nil {
 log.Fatal(err)
 }
}

 go
 
 
package main

import (
 "log"
 "tui"
 "tui/widget"
)

type app struct {
 list *widget.List
}

func (a *app) Init() tui.Cmd { return nil }

func (a *app) Update(msg tui.Msg) (tui.Component, tui.Cmd) {
 switch msg := msg.(type) {
 case tui.KeyMsg:
 if msg.Type == tui.KeyCtrlC {
 return a, tui.QuitCmd()
 }
 }
 a.list, _ = a.list.Update(msg)
 return a, nil
}

func (a *app) Render(buf *tui.Buffer, area tui.Rect) {
 block := tui.NewBlock()
 block.Title = "Items"
 block.Style = tui.NewStyle().Fg(tui.Cyan)
 a.list.SetBlock(block)
 a.list.SetSelectedStyle(tui.NewStyle().Bg(tui.Blue).Fg(tui.White))
 a.list.Render(buf, area)
}

func main() {
 items := []string{"First", "Second", "Third", "Fourth", "Fifth"}
 a := &app{list: widget.NewList(items)}
 if err := tui.Run(a); err != nil {
 log.Fatal(err)
 }
}

Buffer

Mon, 01 Jan 0001 00:00:00 +0000

Buffer is a 2D grid of cells representing terminal content. The framework creates buffers automatically; components write into them during Render.

Creating Buffers

 go
 
buf := tui.NewBuffer(width, height)

Typically you receive a buffer from the framework rather than creating one.

Writing Content

Method	Description
`SetChar(x, y, rune, Style)`	Set a single character
`SetString(x, y, string, Style) int`	Write a string, returns cells written
`SetStringInRect(string, Rect, Style) int`	Write with wrapping, returns lines used
`Fill(Rect, Cell)`	Fill area with a cell
`FillStyle(Rect, Style)`	Apply style to area, preserving characters
`DrawHLine(x, y, width, rune, Style)`	Draw horizontal line
`DrawVLine(x, y, height, rune, Style)`	Draw vertical line

Reading Content

Method	Description
`Get(x, y) Cell`	Read cell at position (emptyCell if out of bounds)

Buffer Operations

Method	Description
`Clear()`	Reset all cells to empty
`Resize(width, height)`	Change dimensions, discard content
`Merge(other, offsetX, offsetY)`	Overlay another buffer at offset
`AddImage(ImagePlacement)`	Register an image for KGP rendering

Diff-Based Rendering

The framework uses Diff internally to produce minimal terminal updates:

Layout

Mon, 01 Jan 0001 00:00:00 +0000

Vertical Split

Split an area into rows with constraints:

 go
 
 
func (a *app) Render(buf *tui.Buffer, area tui.Rect) {
 rows := tui.VSplit(area,
 tui.Fixed(3), // header: exactly 3 rows
 tui.Flex(1), // content: fills remaining space
 tui.Fixed(1), // status bar: exactly 1 row
 )

 renderHeader(buf, rows[0])
 renderContent(buf, rows[1])
 renderStatus(buf, rows[2])
}

Horizontal Split

Split an area into columns:

 go
 
 
cols := tui.HSplit(area,
 tui.Fixed(30), // sidebar: 30 columns wide
 tui.Flex(1), // main: fills the rest
)

Nested Layout

Combine splits for complex layouts:

Style & Color

Mon, 01 Jan 0001 00:00:00 +0000

Color

Color represents a terminal color. The zero value is “no color” (terminal default).

Constructors

Function	Description
`RGB(r, g, b uint8)`	24-bit true color
`Hex(string)`	From hex string (`"#FF6432"` or `"FF6432"`)
`ANSI256(uint8)`	256-color palette index

ANSI 16 Constants

Standard: Black, Red, Green, Yellow, Blue, Magenta, Cyan, White

Bright: BrightBlack, BrightRed, BrightGreen, BrightYellow, BrightBlue, BrightMagenta, BrightCyan, BrightWhite

Methods

Method	Description
`IsZero() bool`	True if this is the default (no) color

Style

Style defines visual attributes for a cell. It is a value type with a chainable builder.

Styling

Mon, 01 Jan 0001 00:00:00 +0000

Colors

TUI supports three color spaces:

 go
 
 
// ANSI 16 standard colors
tui.Red
tui.BrightBlue

// 256-color palette
tui.ANSI256(196)

// 24-bit true color
tui.RGB(255, 128, 0)
tui.Hex("#FF8000")

Style Builder

Styles are value types with a chainable builder:

 go
 
 
style := tui.NewStyle().
 Fg(tui.RGB(200, 100, 50)).
 Bg(tui.Hex("#1a1b26")).
 Bold(true).
 Italic(true).
 Underline(true)

buf.SetString(0, 0, "styled text", style)

Available attributes: Bold, Dim, Italic, Underline, Blink, Reverse, Strikethrough.

Layout

Mon, 01 Jan 0001 00:00:00 +0000

The layout system splits rectangular areas according to constraints.

Functions

VSplit

 go
 
func VSplit(area Rect, constraints ...Constraint) []Rect

Splits vertically (top to bottom). Returns one Rect per constraint.

HSplit

 go
 
func HSplit(area Rect, constraints ...Constraint) []Rect

Splits horizontally (left to right). Returns one Rect per constraint.

Layout

 go
 
func Layout(area Rect, dir Direction, constraints []Constraint) []Rect

General-purpose split with explicit direction (Horizontal or Vertical).

Widgets

Mon, 01 Jan 0001 00:00:00 +0000

Text

Static text display with alignment:

 go
 
 
t := widget.NewText("Hello, World!")
t.SetStyle(tui.NewStyle().Fg(tui.Green))
t.SetAlignment(widget.AlignCenter)
t.Render(buf, area)

Input

Single-line text input with cursor:

 go
 
 
input := widget.NewInput("placeholder...")
input.Focused = true

// In Update:
input, cmd = input.Update(msg)

// In Render:
input.Render(buf, area)

// Read the value:
fmt.Println(input.Value)

Supports Home, End, Ctrl+U (clear left), Ctrl+K (clear right), Ctrl+W (delete word).

List

Scrollable, selectable list with vim keys (j/k/g/G):

Events

Mon, 01 Jan 0001 00:00:00 +0000

All events implement the Msg interface. The framework sends them to your Update method.

Keyboard

 go
 
 
type KeyMsg struct {
 Type KeyType
 Rune rune // only valid when Type == KeyRune
 Alt bool
}

Key Types

Constant	Description
`KeyRune`	Regular character (check `Rune` field)
`KeyEnter`	Enter/Return
`KeyTab` / `KeyBacktab`	Tab / Shift+Tab
`KeyBackspace` / `KeyDelete`	Backspace / Delete
`KeyEscape`	Escape
`KeySpace`	Space
`KeyUp` / `KeyDown` / `KeyLeft` / `KeyRight`	Arrow keys
`KeyHome` / `KeyEnd`	Home / End
`KeyPageUp` / `KeyPageDown`	Page Up / Page Down
`KeyInsert`	Insert
`KeyF1` through `KeyF12`	Function keys
`KeyCtrlA` through `KeyCtrlZ`	Ctrl+letter combinations

Pattern Matching

 go
 
 
switch msg := msg.(type) {
case tui.KeyMsg:
 switch msg.Type {
 case tui.KeyCtrlC:
 return a, tui.QuitCmd()
 case tui.KeyRune:
 switch msg.Rune {
 case 'q':
 return a, tui.QuitCmd()
 }
 }
}

Mouse

 go
 
 
type MouseMsg struct {
 X, Y int
 Button MouseButton
 Action MouseAction
 Alt, Ctrl, Shift bool
}

Button	Description
`MouseLeft` / `MouseMiddle` / `MouseRight`	Standard buttons
`MouseWheelUp` / `MouseWheelDown`	Scroll wheel
`MouseNone`	No button (motion event)

Action	Description
`MousePress`	Button pressed
`MouseRelease`	Button released
`MouseMotion`	Mouse moved

Resize

 go
 
 
type ResizeMsg struct {
 Width, Height int
}

Sent when the terminal dimensions change.

Images

Mon, 01 Jan 0001 00:00:00 +0000

Display from image.Image

The simplest way to show an image:

 go
 
 
imgWidget := widget.NewImage(myImage)
imgWidget.Render(buf, area)

The widget converts the Go image to PNG and transmits it via the Kitty Graphics Protocol.

Display from PNG Data

 go
 
 
data, _ := os.ReadFile("photo.png")
imgWidget := widget.NewImageFromPNG(data)
imgWidget.Render(buf, area)

Display from Raw RGBA

 go
 
 
pixels := tui.SolidColorImageData(100, 100, 255, 0, 0, 255) // red square
imgWidget := widget.NewImageFromRGBA(pixels, 100, 100)
imgWidget.SetCompression(true) // ZLIB compress for efficiency
imgWidget.Render(buf, area)

Display from File Path

 go
 
 
imgWidget := widget.NewImageFromFile("/path/to/image.png")
imgWidget.Render(buf, area)

Pre-Transmitted Images

Transmit once and place multiple times for efficiency:

Animation

Mon, 01 Jan 0001 00:00:00 +0000

Basic Animation Flow

Transmit the base image (frame 1)
Add animation frames with NewAnimation
Encode and send all frames
Control playback

Building an Animation

 go
 
 
mgr := tui.NewImageManager()
imageID := mgr.NextID()

// Transmit base frame
seq := tui.TransmitImageWithID(frame0, imageID)
screen.Flush(seq)

// Build animation with additional frames
anim := tui.NewAnimation(imageID)
anim.AddImageFrame(frame1, 100) // 100ms gap
anim.AddImageFrame(frame2, 100)
anim.AddImageFrame(frame3, 100)
anim.DefaultGap = 100

// Transmit frames
screen.Flush(anim.Encode())

Playback Control

 go
 
 
// Play once
screen.Flush(tui.PlayOnce(imageID))

// Loop infinitely
screen.Flush(tui.PlayLoop(imageID))

// Loop N times
screen.Flush(tui.PlayWithLoops(imageID, 5))

// Stop at current frame
screen.Flush(tui.StopAnimation(imageID))

// Reset to first frame
screen.Flush(tui.ResetAnimation(imageID))

// Jump to a specific frame
screen.Flush(tui.GoToFrame(imageID, 3))

RGBA Frame Animation

Solid-color frames are useful for transitions and testing:

Image

Mon, 01 Jan 0001 00:00:00 +0000

Complete KGP image integration. All functions return escape sequence strings ready to flush to the terminal.

ImagePlacement

ImagePlacement describes an image to render at a terminal position. Use the chainable With* methods to configure.

Creating Placements

 go
 
func NewImagePlacement(x, y, cols, rows int) ImagePlacement

Data Sources

Method	Description
`WithPNG([]byte)`	PNG-encoded data
`WithRGBA([]byte, w, h)`	Raw 32-bit RGBA pixels
`WithRGB([]byte, w, h)`	Raw 24-bit RGB pixels
`WithImage(image.Image)`	Convert Go image to PNG
`WithImageRGBA(image.Image)`	Convert Go image to RGBA
`WithImageRGB(image.Image)`	Convert Go image to RGB
`WithImageID(uint32)`	Reference a pre-transmitted image

Transmission Methods

Method	Description
`WithFile(path, format)`	Read from filesystem
`WithFileOffset(path, format, offset, size)`	Read byte range from file
`WithTempFile(path, format)`	Temp file (terminal auto-deletes)
`WithSharedMemory(name, size, format)`	POSIX shared memory

Display Options

Method	Description
`WithCrop(x, y, w, h)`	Source rectangle for cropping
`WithCellOffset(x, y)`	Pixel offset within starting cell
`WithZIndex(int)`	Layering (negative = below text)
`WithCursorMove(bool)`	Advance cursor after placement
`WithCompression()`	ZLIB compress RGBA/RGB data
`WithVirtual()`	Unicode placeholder mode
`WithRelativeTo(parentID, placeID, offsetH, offsetV)`	Relative positioning

ID Management

Method	Description
`WithID(uint32)`	Set image ID
`WithImageNumber(uint32)`	Set client-side image number
`WithPlacementID(uint32)`	Set placement ID
`WithResponseSuppression(mode)`	Control terminal responses

Image Manager

ImageManager tracks transmitted images and manages lifecycle.

Animation

Mon, 01 Jan 0001 00:00:00 +0000

KGP animation support for building, transmitting, and controlling animated images.

Animation Builder

 go
 
anim := tui.NewAnimation(imageID)

Adding Frames

Method	Description
`AddFrame(data, format, w, h, gapMS)`	Raw pixel data
`AddPNGFrame(pngData, gapMS)`	PNG data
`AddImageFrame(image.Image, gapMS)`	Go image (converted to PNG)
`AddRGBAFrame(data, w, h, gapMS)`	Raw RGBA pixels
`AddRGBFrame(data, w, h, gapMS)`	Raw RGB pixels
`AddSolidFrame(w, h, r, g, b, a, gapMS)`	Solid color frame

Frame Options

Method	Description
`SetFrameComposition(idx, mode, bgFrame)`	Set composition mode
`SetFrameBackground(idx, r, g, b, a)`	Set background color

Fields

Field	Description
`ImageID`	Target image ID
`Frames`	Slice of `AnimationFrame`
`LoopCount`	0=default, 1=infinite, N>1 loops N-1 times
`DefaultGap`	Default frame gap in ms

Encoding

 go
 
func (a *Animation) Encode() string

Returns escape sequences for all frames after the first (frame 1 is the base image, transmitted separately).

Styled Text

Mon, 01 Jan 0001 00:00:00 +0000

Spans

A Span is a run of text with a uniform style:

 go
 
span := tui.NewSpan("important", tui.NewStyle().Fg(tui.Red).Bold(true))

Convenience constructors:

 go
 
 
tui.PlainSpan("normal text")
tui.BoldSpan("bold text")
tui.ColorSpan("colored", tui.Green)
tui.StyledSpan("custom", myStyle)

Styled Lines

Combine spans into a single line:

 go
 
 
line := tui.NewStyledLine(
 tui.BoldSpan("Status: "),
 tui.ColorSpan("OK", tui.Green),
 tui.PlainSpan(" | "),
 tui.ColorSpan("3 warnings", tui.Yellow),
)
line.Render(buf, 0, 0)

Styled Text Blocks

Stack multiple lines:

Focus and Input

Mon, 01 Jan 0001 00:00:00 +0000

Focus Manager

Track focus across named components:

 go
 
 
focus := tui.NewFocusManager("sidebar", "content", "input")

focus.Next() // advance to next
focus.Prev() // go to previous
focus.Focus("input") // focus by name
focus.IsFocused("sidebar") // check current
focus.Current() // get current name
focus.Index() // get current index

Tab-Based Focus Switching

 go
 
 
func (a *app) Update(msg tui.Msg) (tui.Component, tui.Cmd) {
 switch msg := msg.(type) {
 case tui.KeyMsg:
 if msg.Type == tui.KeyTab {
 a.focus.Next()
 return a, nil
 }
 if msg.Type == tui.KeyBacktab {
 a.focus.Prev()
 return a, nil
 }
 }

 // Delegate to focused component
 switch a.focus.Current() {
 case "sidebar":
 a.list, _ = a.list.Update(msg)
 case "content":
 a.viewport, _ = a.viewport.Update(msg)
 case "input":
 a.input, _ = a.input.Update(msg)
 }
 return a, nil
}

Visual Focus Indication

Use the theme system to style focused borders:

Widgets

Mon, 01 Jan 0001 00:00:00 +0000

All widgets are in the tui/widget package. Interactive widgets follow the pattern:

 go
 
 
widget, cmd = widget.Update(msg) // in Update
widget.Render(buf, area) // in Render

Most widgets support SetBlock(tui.Block) for borders and titles.

Text

Static text display with alignment.

 go
 
func NewText(content string) *Text

Method	Description
`SetStyle(Style)`	Text style
`SetAlignment(Alignment)`	`AlignLeft`, `AlignCenter`, `AlignRight`
`SetBlock(Block)`	Border

Input

Single-line text input with cursor.

 go
 
func NewInput(placeholder string) *Input

Field	Description
`Value`	Current text value
`Focused`	Whether input accepts keys

Method	Description
`Update(Msg) (*Input, Cmd)`	Handle key events
`Focus() Cmd`	Return focus command
`SetBlock(Block)`	Border
`SetStyle(Style)`	Text style

Keyboard: Home, End, Left, Right, Backspace, Delete, Ctrl+U, Ctrl+K, Ctrl+W.

Timers

Mon, 01 Jan 0001 00:00:00 +0000

Periodic Tick

Send a message at regular intervals:

 go
 
 
func (a *app) Init() tui.Cmd {
 return tui.TickCmd(100 * time.Millisecond)
}

func (a *app) Update(msg tui.Msg) (tui.Component, tui.Cmd) {
 switch msg.(type) {
 case tui.TickMsg:
 a.frame++
 return a, tui.TickCmd(100 * time.Millisecond)
 }
 return a, nil
}

FPS-Based Tick

 go
 
 
// 30 FPS
return tui.TickEvery(30)

Delayed Message

Send a message after a one-time delay:

Demo Application

Mon, 01 Jan 0001 00:00:00 +0000

Running the Demos

The examples/ directory contains runnable demo applications:

 bash
 
 
# Simple list and input
go run ./examples/hello

# Full dashboard with tabs, sparklines, tree, form
go run ./examples/demo

# KGP image rendering
go run ./examples/image

# KGP animation
go run ./examples/animation

Demo Application Structure

The full demo (examples/demo/main.go) showcases:

Tab navigation with 5 tabs (Dashboard, Table, Logs, Tree, Form)
Focus management with Alt+Tab to switch focus zones
Nord theme with derived styles for borders, status bar, selection
Live sparkline updated via periodic tick
Gauge widget showing real-time CPU simulation
Animated spinner in the status bar
Tree view with expand/collapse
Form with tab-based field navigation
Scrollable viewport for log viewing

Architecture Pattern

The demo follows a common pattern for multi-tab applications:

Terminal Support

Mon, 01 Jan 0001 00:00:00 +0000

TUI works in any terminal that supports ANSI escape sequences. KGP image features require additional protocol support.

Text Features

All text-based features (widgets, layout, styling, events) work in any modern terminal:

Feature	Requirement
Basic rendering	ANSI escape sequences
16 colors	ANSI color support
256 colors	256-color mode
True color (24-bit)	True color support
Mouse tracking	SGR mouse mode
Alternate screen	xterm alternate screen

KGP Image Features

Terminal	Support	Notes
Kitty	Full	Version 0.19.0+
WezTerm	Partial	Core features supported
Konsole	Experimental	KDE Konsole

Verify KGP Support

 go
 
 
screen.Flush(tui.QueryKGPSupport())
// Terminal responds with OK if supported

Query specific capabilities:

TUI — Terminal User Interface Framework for Go on TUI

Component

Interface

Init

Update

Hello World

Minimal Application

With a List Widget

Buffer

Creating Buffers

Writing Content

Reading Content

Buffer Operations

Diff-Based Rendering

Layout

Vertical Split

Horizontal Split

Nested Layout

Style & Color

Color

Constructors

ANSI 16 Constants

Methods

Style

Styling

Colors

Style Builder

Layout

Functions

VSplit

HSplit

Layout

Widgets

Text

Input

List

Events

Keyboard

Key Types

Pattern Matching

Mouse

Resize

Images

Display from image.Image

Display from PNG Data

Display from Raw RGBA

Display from File Path

Pre-Transmitted Images

Animation

Basic Animation Flow

Building an Animation

Playback Control

RGBA Frame Animation

Image

ImagePlacement

Creating Placements

Data Sources

Transmission Methods

Display Options

ID Management

Image Manager

Animation

Animation Builder

Adding Frames

Frame Options

Fields

Encoding

Styled Text

Spans

Styled Lines

Styled Text Blocks

Focus and Input

Focus Manager

Tab-Based Focus Switching

Visual Focus Indication

Widgets

Text

Input

Timers

Periodic Tick