# go-tui — Complete Reference for LLMs
> Declarative terminal UI framework for Go with templ-like syntax and flexbox layout.
> Pure Go, minimal dependencies, generates type-safe code from `.gsx` templates.
## Installation
```bash
go get github.com/grindlemire/go-tui
go install github.com/grindlemire/go-tui/cmd/tui@latest
```
## CLI Commands
```bash
tui generate [path...] # Generate Go code from .gsx files
tui check [path...] # Validate .gsx files without writing output
tui fmt [path...] # Format .gsx files
tui fmt --check [path...] # Check formatting without modifying
tui lsp # Start language server (stdio)
```
## Architecture
```
.gsx files → tui generate → _gsx.go files → go build → binary
```
At runtime: Event Loop → Layout Engine (flexbox) → Double-buffered Render → ANSI Terminal Output
## GSX Syntax
`.gsx` files are Go files with a `templ` keyword for declaring UI components. They compile to standard Go code.
### Pure Components (stateless)
```gsx
package main
import tui "github.com/grindlemire/go-tui"
templ Greeting(name string) {
{"Hello, " + name}
}
// With children slot
templ Card(title string) {
{title}
{children...}
}
// Usage
templ App() {
@Card("Info") {
@Greeting("Alice")
}
}
```
### Struct Components (stateful)
```gsx
type counter struct {
count *tui.State[int]
}
func Counter() *counter {
return &counter{count: tui.NewState(0)}
}
func (c *counter) KeyMap() tui.KeyMap {
return tui.KeyMap{
tui.On(tui.KeyEscape, func(ke tui.KeyEvent) { ke.App().Stop() }),
tui.On(tui.Rune('+'), func(ke tui.KeyEvent) {
c.count.Update(func(v int) int { return v + 1 })
}),
}
}
templ (c *counter) Render() {
{fmt.Sprintf("Count: %d", c.count.Get())}
}
```
### Struct Components with Children
```gsx
type panel struct {
title string
children []*tui.Element
}
func NewPanel(title string, children []*tui.Element) *panel {
return &panel{title: title, children: children}
}
templ (p *panel) Render() {
{p.title}
{children...}
}
```
### Control Flow
```gsx
// Conditionals
if condition {
True
} else if otherCondition {
Other
} else {
Default
}
// Loops
for i, item := range items {
{fmt.Sprintf("%d: %s", i, item)}
}
// Local element binding
badge := {label}
{badge}
```
### Go Expressions
```gsx
{fmt.Sprintf("Count: %d", c.count.Get())}
Dynamic class
content
```
## main.go Pattern
```go
package main
import (
"fmt"
"os"
tui "github.com/grindlemire/go-tui"
)
func main() {
app, err := tui.NewApp(
tui.WithRootComponent(MyComponent()),
// Optional:
// tui.WithMouse(),
// tui.WithFrameRate(60),
// tui.WithInlineHeight(10),
// tui.WithGlobalKeyHandler(func(ke tui.KeyEvent) bool { return false }),
)
if err != nil {
fmt.Fprintf(os.Stderr, "Error: %v\n", err)
os.Exit(1)
}
defer app.Close()
if err := app.Run(); err != nil {
fmt.Fprintf(os.Stderr, "Error: %v\n", err)
os.Exit(1)
}
}
```
## Single-Frame Printing
For CLI tools that render styled output once and exit, without starting an interactive app:
```go
// Print to stdout (auto-detects terminal width, falls back to 80)
tui.Print(MyComponent("hello"))
// Return as ANSI string (no trailing newline)
s := tui.Sprint(view, tui.WithPrintWidth(80))
// Write to any io.Writer (appends trailing newline)
tui.Fprint(w, view, tui.WithPrintWidth(120))
```
All three accept a `Viewable` (generated `.gsx` views and raw `*Element` values). Same components work with both `Print` and `App.Run()`.
```go
// PrintOption
tui.WithPrintWidth(w int) // Explicit width; default: auto-detect, fallback 80
```
## Built-in Elements
### Container Elements
| Element | Description | Default Direction |
|---------|-------------|-------------------|
| `` | Block flex container (primary layout element) | Row |
| `
` | Inline text container | — |
| `` | Paragraph with automatic text wrapping | — |
| `
` | Unordered list container | Column |
| `` | List item (auto bullet prefix) | — |
| `` | Clickable element | — |
| `` | Full-screen overlay dialog with backdrop | — |
| `` | Table container | Column |
### Self-Closing (Void) Elements
| Element | Description |
|---------|-------------|
| ``) are not supported because the buffer covers only a partial terminal region. Use `app.EnterAlternateScreen()` to switch to full-screen before opening a modal, then `app.ExitAlternateScreen()` when it closes.
### StreamAbove
`app.StreamAbove()` returns a `*StreamWriter` for character-by-character streaming above the inline widget. The writer implements `io.WriteCloser` and adds `WriteStyled` and `WriteGradient` methods. Goroutine-safe. Close it when done to finalize the partial line.
```go
go func() {
w := app.StreamAbove()
// Plain write (backward compatible)
fmt.Fprint(w, "hello ")
// Styled write
w.WriteStyled("bold text", tui.NewStyle().Bold().Foreground(tui.Red))
// Gradient write (per-character color interpolation)
grad := tui.NewGradient(tui.Cyan, tui.Magenta)
w.WriteGradient("gradient text", grad)
// Gradient with base style (bold + gradient foreground)
w.WriteGradient("bold gradient", grad, tui.NewStyle().Bold())
w.Close()
}()
```
`WriteStyled(text, style)` wraps text in ANSI style prefix/reset. `WriteGradient(text, gradient, base...)` writes each character with an interpolated gradient foreground; optional base style adds attributes (bold, italic, etc.) and background.
Returns a no-op writer when not in inline mode. Only one stream writer is active at a time; calling `StreamAbove()` again finalizes the previous one. `PrintAbove`/`PrintAboveln` also finalize any active stream before printing.
### PrintAboveElement
`app.PrintAboveElement(el)` renders an element tree at the terminal width and inserts the resulting rows into the inline scrollback as static ANSI text. Works with templ function output. No-op outside inline mode. Must be called from the main event loop. `QueuePrintAboveElement(el)` is the goroutine-safe variant.
`StreamWriter.WriteElement(el)` inserts a rendered element mid-stream. Finalizes the current partial line first.
```go
// Standalone
app.PrintAboveElement(DataTable(rows))
// Mid-stream
w := app.StreamAbove()
w.Write([]byte("Here's the data:\n"))
w.WriteElement(DataTable(rows))
w.Write([]byte("Done.\n"))
w.Close()
```
## Common Layout Patterns
```gsx
// Full-screen with header/content/footer
// Sidebar + main
// Centered card
// Dashboard grid
```
## Modal Example
**Important:** Modals require full-screen mode. They are silently ignored in inline mode (`WithInlineHeight`). To show a modal from an inline app, call `app.EnterAlternateScreen()` first, then `app.ExitAlternateScreen()` when the modal closes.
```gsx
Confirm?
Cancel
OK
```
Bottom sheet variant:
```gsx
Action?
Cancel
Go
```
## Testing
```go
// MockTerminal captures rendering output
term := tui.NewMockTerminal(80, 24)
// MockEventReader provides scripted events
reader := tui.NewMockEventReader(
tui.KeyEvent{Key: tui.KeyRune, Rune: 'a'},
tui.KeyEvent{Key: tui.KeyEscape},
)
// Table-driven test pattern
type tc struct { /* fields */ }
tests := map[string]tc{ "name": { /* values */ } }
for name, tt := range tests {
t.Run(name, func(t *testing.T) { /* test */ })
}
```
## Element Option Functions (Go API)
When building elements programmatically (outside .gsx):
```go
el := tui.New(
tui.WithWidth(30),
tui.WithHeight(10),
tui.WithWidthPercent(50),
tui.WithWidthAuto(),
tui.WithMinWidth(10),
tui.WithMaxWidth(60),
tui.WithDirection(tui.Column),
tui.WithJustify(tui.JustifyCenter),
tui.WithAlign(tui.AlignCenter),
tui.WithGap(2),
tui.WithFlexGrow(1.0),
tui.WithFlexShrink(0),
tui.WithPadding(2),
tui.WithMargin(1),
tui.WithBorder(tui.BorderRounded),
tui.WithBackground(tui.Cyan),
tui.WithText("content"),
tui.WithTextStyle(tui.NewStyle().Bold()),
tui.WithTextAlign(tui.TextAlignCenter),
tui.WithScrollable(tui.ScrollVertical),
tui.WithFocusable(true),
tui.WithHidden(true),
tui.WithTruncate(true),
tui.WithTextGradient(tui.NewGradient(tui.Cyan, tui.Magenta)),
tui.WithBackgroundGradient(tui.NewGradient(tui.Blue, tui.Cyan)),
tui.WithBorderGradient(tui.NewGradient(tui.Cyan, tui.Magenta)),
)
```
## Cross-Component Communication
```gsx
// Producer component
type producer struct {
bus *tui.Events[string]
}
func Producer() *producer {
return &producer{bus: tui.NewEvents[string]("my.topic")}
}
func (p *producer) KeyMap() tui.KeyMap {
return tui.KeyMap{
tui.On(tui.Rune('e'), func(ke tui.KeyEvent) { p.bus.Emit("event!") }),
}
}
// Consumer component (separate, no direct reference to producer)
type consumer struct {
bus *tui.Events[string]
messages *tui.State[[]string]
}
func Consumer() *consumer {
c := &consumer{
bus: tui.NewEvents[string]("my.topic"), // same topic string
messages: tui.NewState([]string{}),
}
c.bus.Subscribe(func(msg string) {
c.messages.Set(append(c.messages.Get(), msg))
})
return c
}
```
## Buffer / Rendering Internals
- Double-buffered character grid (front/back buffers)
- Diff-based rendering: only changed cells are written to terminal
- Each cell stores: Rune, Style, Width (CJK support)
- ANSI escape sequences for cursor movement, colors, text attributes
- Automatic color capability detection and fallback