Examples on TUI

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)
 }
}

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:

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.

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):

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:

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:

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:

Examples on TUI

Hello World

Minimal Application

With a List Widget

Layout

Vertical Split

Horizontal Split

Nested Layout

Styling

Colors

Style Builder

Widgets

Text

Input

List

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

Styled Text

Spans

Styled Lines

Styled Text Blocks

Focus and Input

Focus Manager

Tab-Based Focus Switching

Visual Focus Indication

Timers

Periodic Tick

FPS-Based Tick

Delayed Message

Demo Application

Running the Demos

Demo Application Structure

Architecture Pattern