gitstack
Feature requests Sign in
Feature requests Sign in

grindlemire/go-tui code browser

23.2 KB markdown 708 lines 2026-03-23 · a47141f raw

Multi-Component Applications

Overview

Real applications are rarely a single component. A file explorer needs a sidebar, a content panel, a search bar. A chat app needs a message list and an input widget, at minimum. Each piece has its own state and behavior, but they need to coordinate.

go-tui handles this through shared state and the mount system. Parent components create State[T] values and pass them to children through constructors. When any component changes a shared state value, every component that reads it sees the update on the next render. The mount system caches child component instances across renders, so each child keeps its own local state even when the parent re-renders.

This guide walks through splitting code across files, sharing state between components, conditional KeyMaps, and architecture patterns for larger apps.

Multiple .gsx Files

Each component can live in its own .gsx file. All files in the same package share scope, so components defined in one file are callable from another without imports:

myapp/
  main.go
  app.gsx          -> app_gsx.go
  sidebar.gsx      -> sidebar_gsx.go
  search.gsx       -> search_gsx.go   (search bar + content panel)

Run tui generate ./... and it processes every .gsx file in the package, producing a corresponding _gsx.go file for each. The generated files are standard Go, so all the components end up in the same package and can reference each other directly.

There's no strict rule about how many components go in one file. A small pure component that's only used alongside its parent can share a file. A struct component with its own state and key handling usually deserves its own file. Split when it makes the code easier to navigate.

Shared State

The main coordination mechanism between components is shared *tui.State[T]. The parent creates a state value and passes the pointer to each child that needs it. Because they all hold the same pointer, a .Set() or .Update() from any component marks the UI dirty and every component sees the new value on the next render.

Here's the pattern. A root component creates a category state and hands it to both a sidebar and a content panel:

package main

import tui "github.com/grindlemire/go-tui"

type myApp struct {
    category *tui.State[string]
}

func MyApp() *myApp {
    return &myApp{
        category: tui.NewState("Documents"),
    }
}

func (a *myApp) KeyMap() tui.KeyMap {
    return tui.KeyMap{
        tui.On(tui.KeyCtrlC, func(ke tui.KeyEvent) { ke.App().Stop() }),
    }
}

templ (a *myApp) Render() {
    <div class="flex h-full">
        @Sidebar(a.category)
        @Content(a.category)
    </div>
}

The sidebar receives the shared state and also creates its own local selected state for tracking which list item has the cursor:

package main

import tui "github.com/grindlemire/go-tui"

var categories = []string{"Documents", "Images", "Music", "Projects", "Downloads"}

type sidebar struct {
    category *tui.State[string]
    selected *tui.State[int]
}

func Sidebar(category *tui.State[string]) *sidebar {
    return &sidebar{
        category: category,
        selected: tui.NewState(0),
    }
}

func (s *sidebar) KeyMap() tui.KeyMap {
    return tui.KeyMap{
        tui.On(tui.Rune('j'), func(ke tui.KeyEvent) {
            s.selected.Update(func(v int) int {
                if v >= len(categories)-1 {
                    return 0
                }
                return v + 1
            })
            s.category.Set(categories[s.selected.Get()])
        }),
        tui.On(tui.Rune('k'), func(ke tui.KeyEvent) {
            s.selected.Update(func(v int) int {
                if v <= 0 {
                    return len(categories) - 1
                }
                return v - 1
            })
            s.category.Set(categories[s.selected.Get()])
        }),
    }
}

templ (s *sidebar) Render() {
    <div class="flex-col border-single shrink-0 px-1" width={20}>
        <span class="text-gradient-cyan-magenta font-bold">Folders</span>
        <hr />
        for i, cat := range categories {
            if i == s.selected.Get() {
                <span class="text-cyan font-bold">{"> " + cat}</span>
            } else {
                <span class="font-dim">{"  " + cat}</span>
            }
        }
    </div>
}

The content panel reads the same category state to display the right files:

package main

import (
    "fmt"

    tui "github.com/grindlemire/go-tui"
)

var filesByCategory = map[string][]string{
    "Documents": {"report.pdf", "notes.md", "budget.xlsx", "readme.txt"},
    "Images":    {"photo.jpg", "screenshot.png", "logo.svg", "banner.gif"},
    "Music":     {"song.mp3", "album.flac", "podcast.ogg"},
    "Projects":  {"go-tui/", "website/", "api-server/"},
    "Downloads": {"setup.exe", "archive.zip", "data.csv"},
}

type content struct {
    category *tui.State[string]
}

func Content(category *tui.State[string]) *content {
    return &content{category: category}
}

templ (c *content) Render() {
    <div class="flex-col grow px-2">
        <span class="font-bold text-cyan">{c.category.Get() + "/"}</span>
        <hr />
        files := filesByCategory[c.category.Get()]
        for i, file := range files {
            if i == len(files)-1 {
                <span>{fmt.Sprintf("└── %s", file)}</span>
            } else {
                <span>{fmt.Sprintf("├── %s", file)}</span>
            }
        }
    </div>
}

When the sidebar calls s.category.Set(categories[s.selected.Get()]), the content panel picks it up through c.category.Get() on the next render. Neither component knows about the other. They just read and write the same state.

What Gets Shared vs. What Stays Local

A good rule of thumb: share state that represents data two or more components need to agree on. Keep state local when it's purely about that component's internal behavior.

In the example above, category is shared because both the sidebar and the content panel need it. But selected is local to the sidebar because only the sidebar cares about which list item has the cursor highlight.

Conditional KeyMaps

KeyMap() is called on every render pass, so you can return different bindings depending on component state. This is how you implement modes: a search bar that captures all keystrokes when active, a sidebar that ignores navigation keys when collapsed, or a vim-style editor with distinct modes.

Here's a search bar that returns nil (no bindings) when inactive, and captures all runes when active:

package main

import tui "github.com/grindlemire/go-tui"

type searchBar struct {
    active *tui.State[bool]
    query  *tui.State[string]
}

func SearchBar(active *tui.State[bool], query *tui.State[string]) *searchBar {
    return &searchBar{active: active, query: query}
}

func (s *searchBar) KeyMap() tui.KeyMap {
    if !s.active.Get() {
        return nil
    }
    return tui.KeyMap{
        tui.OnStop(tui.AnyRune,s.appendChar),
        tui.OnStop(tui.KeyBackspace, s.deleteChar),
        tui.OnStop(tui.KeyEnter, s.submit),
        tui.OnStop(tui.KeyEscape, s.deactivate),
    }
}

func (s *searchBar) appendChar(ke tui.KeyEvent) {
    s.query.Set(s.query.Get() + string(ke.Rune))
}

func (s *searchBar) deleteChar(ke tui.KeyEvent) {
    q := s.query.Get()
    if len(q) > 0 {
        s.query.Set(q[:len(q)-1])
    }
}

func (s *searchBar) submit(ke tui.KeyEvent) {
    s.active.Set(false)
}

func (s *searchBar) deactivate(ke tui.KeyEvent) {
    s.active.Set(false)
    s.query.Set("")
}

templ (s *searchBar) Render() {
    <div class="shrink-0">
        if s.active.Get() {
            <hr />
            <div class="px-1 flex gap-1">
                <span class="text-cyan font-bold">Search:</span>
                <span>{s.query.Get()}</span>
                <span class="text-cyan blink">_</span>
            </div>
        }
    </div>
}

The OnStop variants prevent the event from reaching other components. When the search bar is active, pressing j types a j into the search field instead of moving the sidebar cursor. When it's inactive, it returns nil and stays out of the way entirely.

The root component can also have conditional bindings. For example, only registering / to open search and q to quit when search is not active:

func (a *myApp) KeyMap() tui.KeyMap {
    km := tui.KeyMap{
        tui.On(tui.KeyCtrlC, func(ke tui.KeyEvent) { ke.App().Stop() }),
    }
    if !a.searchActive.Get() {
        km = append(km, tui.On(tui.Rune('/'), func(ke tui.KeyEvent) {
            a.searchActive.Set(true)
        }))
        km = append(km, tui.On(tui.Rune('q'), func(ke tui.KeyEvent) {
            ke.App().Stop()
        }))
    }
    return km
}

This keeps the q key from quitting the app while you're typing a search query.

Event Dispatch Order

The framework collects key bindings from all mounted components by walking the element tree in breadth-first order. Components closer to the root of the tree appear earlier in the dispatch list. For a given key event, every matching handler fires in tree order unless a Stop handler consumes the event first.

For the file explorer layout:

myApp (root)
├── Sidebar
├── Content
└── SearchBar

The dispatch order is: myApp first, then Sidebar, then Content, then SearchBar. If the search bar registers OnStop(tui.AnyRune, ...) for all runes, those handlers run after the root and sidebar handlers for the same key. But because the search bar's handler has Stop=true, it prevents any subsequent handlers from firing. Since the search bar is last in tree order for this layout, the stop flag mainly serves as documentation of intent and future-proofing.

If you need a child component to intercept a key before its parent sees it, restructure the tree so the intercepting component appears first in BFS order, or have the parent check state before registering its bindings (the conditional KeyMap pattern above).

Two components cannot both register Stop handlers for the same key pattern at the same time. The framework validates this and returns an error. This catches bugs early: if two components both claim exclusive ownership of Escape, something needs to change.

Sub-Component Mounting

When a struct component renders another struct component using @Component(args) syntax, the generated code calls app.Mount():

// Generated from: @Sidebar(a.category)
app.Mount(a, 0, func() tui.Component {
    return Sidebar(a.category)
})

Mount takes the parent component, a position index, and a factory function. It uses the (parent, index) pair as a cache key:

  • First render: The factory runs, creating a new component instance. The framework calls BindApp() to wire up state fields, then calls Init() if the component implements Initializer. The instance is cached.
  • Subsequent renders: The cached instance is reused. If the component implements PropsUpdater, a fresh instance is created from the factory and passed to UpdateProps() so the cached instance can pick up changed props without losing its internal state.

This is why a child's local state survives parent re-renders. The sidebar's selected state persists because the framework returns the cached sidebar instance instead of creating a new one.

When a component is no longer rendered (removed from the tree by an if condition, for example), the framework's mark-and-sweep cleanup calls the cleanup function returned by Init() and removes the instance from cache.

You don't call Mount directly. The code generator handles it. Write @Sidebar(a.category) in your .gsx file and the generated code does the rest.

Generated BindApp and UpdateProps

The code generator automatically produces BindApp and UpdateProps methods for struct components. BindApp wires every *tui.State and *tui.Events field to the running app so that .Set() calls mark the UI dirty. UpdateProps copies non-state fields from a fresh instance to the cached one, keeping state intact while updating configuration.

You don't write these methods by hand. For a component with one shared state field and one local state field:

// Auto-generated
func (s *sidebar) BindApp(app *tui.App) {
    if s.category != nil {
        s.category.BindApp(app)
    }
    if s.selected != nil {
        s.selected.BindApp(app)
    }
    if s.expanded != nil {
        s.expanded.BindApp(app)
    }
}

Architecture Patterns

Orchestrator Pattern

One root component owns all shared state. Children receive state through their constructors and read/write it, but the root is the single source of truth.

type myApp struct {
    searchActive *tui.State[bool]
    query        *tui.State[string]
    category     *tui.State[string]
}

func MyApp() *myApp {
    return &myApp{
        searchActive: tui.NewState(false),
        query:        tui.NewState(""),
        category:     tui.NewState("Documents"),
    }
}

templ (a *myApp) Render() {
    <div class="flex-col h-full border-rounded border-cyan">
        <div class="flex justify-center px-1 shrink-0">
            <span class="text-gradient-cyan-magenta font-bold">File Explorer</span>
        </div>
        <hr />
        <div class="flex grow min-h-0 overflow-hidden">
            @Sidebar(a.category)
            @Content(a.category, a.query)
        </div>
        @SearchBar(a.searchActive, a.query)
        <hr />
        <div class="flex justify-center px-1 shrink-0">
            <span class="font-dim">/search | Ctrl+B sidebar | j/k navigate | q quit</span>
        </div>
    </div>
}

This works well for apps where a few pieces of state drive the whole UI. The root component's KeyMap can check searchActive to decide which keys to register, and every child component reads the same state values.

Distributed State

Each component owns the state it's responsible for. Coordination happens through a small number of shared state values, while most state stays local.

In the file explorer example, the sidebar owns expanded and selected locally. Only category is shared with the content panel. The search bar owns its text-input mechanics locally; only active and query are shared.

This scales better as apps grow. Each component manages its own concerns, and you only share what's necessary for cross-component coordination.

Choosing Between Them

For small apps (2-3 components, a handful of state values), the orchestrator pattern is simpler and keeps everything in one place.

For larger apps, distributed state keeps individual components self-contained. New components can be added without modifying the root, as long as they receive the shared state they need through their constructor.

Most apps end up somewhere in between: a root that owns the shared coordination state, with children that manage their own internal state.

Complete Example

Here's a full file explorer with three components: sidebar, content panel, and search bar. The root component wires them together with shared state.

app.gsx:

package main

import tui "github.com/grindlemire/go-tui"

type myApp struct {
    searchActive *tui.State[bool]
    query        *tui.State[string]
    category     *tui.State[string]
}

func MyApp() *myApp {
    return &myApp{
        searchActive: tui.NewState(false),
        query:        tui.NewState(""),
        category:     tui.NewState("Documents"),
    }
}

func (a *myApp) KeyMap() tui.KeyMap {
    km := tui.KeyMap{
        tui.On(tui.KeyCtrlC, func(ke tui.KeyEvent) { ke.App().Stop() }),
    }
    if !a.searchActive.Get() {
        km = append(km, tui.On(tui.Rune('/'), func(ke tui.KeyEvent) {
            a.searchActive.Set(true)
        }))
        km = append(km, tui.On(tui.Rune('q'), func(ke tui.KeyEvent) {
            ke.App().Stop()
        }))
    }
    return km
}

templ (a *myApp) Render() {
    <div class="flex-col h-full border-rounded border-cyan">
        <div class="flex justify-center px-1 shrink-0">
            <span class="text-gradient-cyan-magenta font-bold">File Explorer</span>
        </div>
        <hr />
        <div class="flex grow min-h-0 overflow-hidden">
            @Sidebar(a.category)
            @Content(a.category, a.query)
        </div>
        @SearchBar(a.searchActive, a.query)
        <hr />
        <div class="flex justify-center px-1 shrink-0">
            <span class="font-dim">/search | Ctrl+B sidebar | j/k navigate | q quit</span>
        </div>
    </div>
}

sidebar.gsx:

package main

import tui "github.com/grindlemire/go-tui"

type sidebar struct {
    category *tui.State[string]
    expanded *tui.State[bool]
    selected *tui.State[int]
}

var categories = []string{"Documents", "Images", "Music", "Projects", "Downloads"}

func Sidebar(category *tui.State[string]) *sidebar {
    return &sidebar{
        category: category,
        expanded: tui.NewState(true),
        selected: tui.NewState(0),
    }
}

func (s *sidebar) KeyMap() tui.KeyMap {
    km := tui.KeyMap{
        tui.On(tui.KeyCtrlB, func(ke tui.KeyEvent) {
            s.expanded.Set(!s.expanded.Get())
        }),
    }
    if s.expanded.Get() {
        km = append(km, tui.On(tui.Rune('j'), func(ke tui.KeyEvent) { s.moveDown() }))
        km = append(km, tui.On(tui.Rune('k'), func(ke tui.KeyEvent) { s.moveUp() }))
        km = append(km, tui.On(tui.KeyDown, func(ke tui.KeyEvent) { s.moveDown() }))
        km = append(km, tui.On(tui.KeyUp, func(ke tui.KeyEvent) { s.moveUp() }))
        km = append(km, tui.On(tui.KeyEnter, func(ke tui.KeyEvent) {
            idx := s.selected.Get()
            if idx >= 0 && idx < len(categories) {
                s.category.Set(categories[idx])
            }
        }))
    }
    return km
}

func (s *sidebar) moveDown() {
    s.selected.Update(func(v int) int {
        if v >= len(categories)-1 {
            return 0
        }
        return v + 1
    })
    s.category.Set(categories[s.selected.Get()])
}

func (s *sidebar) moveUp() {
    s.selected.Update(func(v int) int {
        if v <= 0 {
            return len(categories) - 1
        }
        return v - 1
    })
    s.category.Set(categories[s.selected.Get()])
}

func (s *sidebar) sidebarWidth() int {
    if s.expanded.Get() {
        return 22
    }
    return 5
}

templ (s *sidebar) Render() {
    <div class="flex-col border-single shrink-0" width={s.sidebarWidth()}>
        if s.expanded.Get() {
            <div class="flex-col px-1">
                <span class="text-gradient-cyan-magenta font-bold">Folders</span>
            </div>
            <hr />
            <div class="flex-col px-1 grow">
                for i, cat := range categories {
                    if i == s.selected.Get() {
                        <span class="text-cyan font-bold">{"> " + cat}</span>
                    } else {
                        <span class="font-dim">{"  " + cat}</span>
                    }
                }
            </div>
            <hr />
            <div class="flex-col px-1">
                <span class="font-dim text-cyan">Ctrl+B hide</span>
            </div>
        } else {
            <span class="text-cyan font-bold px-1">F</span>
        }
    </div>
}

search.gsx (search bar and content panel):

package main

import (
    "fmt"
    "strings"

    tui "github.com/grindlemire/go-tui"
)

type searchBar struct {
    active *tui.State[bool]
    query  *tui.State[string]
}

func SearchBar(active *tui.State[bool], query *tui.State[string]) *searchBar {
    return &searchBar{active: active, query: query}
}

func (s *searchBar) KeyMap() tui.KeyMap {
    if !s.active.Get() {
        return nil
    }
    return tui.KeyMap{
        tui.OnStop(tui.AnyRune,s.appendChar),
        tui.OnStop(tui.KeyBackspace, s.deleteChar),
        tui.OnStop(tui.KeyEnter, s.submit),
        tui.OnStop(tui.KeyEscape, s.deactivate),
    }
}

func (s *searchBar) appendChar(ke tui.KeyEvent) {
    s.query.Set(s.query.Get() + string(ke.Rune))
}

func (s *searchBar) deleteChar(ke tui.KeyEvent) {
    q := s.query.Get()
    if len(q) > 0 {
        s.query.Set(q[:len(q)-1])
    }
}

func (s *searchBar) submit(ke tui.KeyEvent) {
    s.active.Set(false)
}

func (s *searchBar) deactivate(ke tui.KeyEvent) {
    s.active.Set(false)
    s.query.Set("")
}

templ (s *searchBar) Render() {
    <div class="shrink-0">
        if s.active.Get() {
            <hr />
            <div class="px-1 flex gap-1">
                <span class="text-cyan font-bold">Search:</span>
                <span>{s.query.Get()}</span>
                <span class="text-cyan blink">_</span>
            </div>
        }
    </div>
}

// Content displays files for the selected category
type content struct {
    category *tui.State[string]
    query    *tui.State[string]
}

func Content(category *tui.State[string], query *tui.State[string]) *content {
    return &content{category: category, query: query}
}

var filesByCategory = map[string][]string{
    "Documents": {"report.pdf", "notes.md", "budget.xlsx", "readme.txt", "design.doc"},
    "Images":    {"photo.jpg", "screenshot.png", "logo.svg", "banner.gif", "icon.ico"},
    "Music":     {"song.mp3", "album.flac", "podcast.ogg", "ringtone.wav"},
    "Projects":  {"go-tui/", "website/", "api-server/", "mobile-app/", "scripts/"},
    "Downloads": {"setup.exe", "archive.zip", "data.csv", "patch-v2.tar.gz"},
}

func (c *content) filteredFiles() []string {
    cat := c.category.Get()
    files, ok := filesByCategory[cat]
    if !ok {
        return nil
    }
    q := strings.ToLower(c.query.Get())
    if q == "" {
        return files
    }
    var result []string
    for _, f := range files {
        if strings.Contains(strings.ToLower(f), q) {
            result = append(result, f)
        }
    }
    return result
}

templ (c *content) Render() {
    <div class="flex-col grow px-2 overflow-hidden">
        <span class="font-bold text-cyan">{c.category.Get() + "/"}</span>
        <hr />
        for i, file := range c.filteredFiles() {
            if i == len(c.filteredFiles())-1 {
                <span>{fmt.Sprintf("└── %s", file)}</span>
            } else {
                <span>{fmt.Sprintf("├── %s", file)}</span>
            }
        }
        if len(c.filteredFiles()) == 0 {
            <span class="font-dim">No matching files</span>
        }
        if c.query.Get() != "" {
            <br />
            <span class="font-dim">{fmt.Sprintf("Filtering: \"%s\"", c.query.Get())}</span>
        }
    </div>
}

main.go:

package main

import (
    "fmt"
    "os"

    tui "github.com/grindlemire/go-tui"
)

func main() {
    app, err := tui.NewApp(
        tui.WithRootComponent(MyApp()),
    )
    if err != nil {
        fmt.Fprintf(os.Stderr, "Failed to create app: %v\n", err)
        os.Exit(1)
    }
    defer app.Close()

    if err := app.Run(); err != nil {
        fmt.Fprintf(os.Stderr, "App error: %v\n", err)
        os.Exit(1)
    }
}

Generate and run:

tui generate ./...
go run .

Here's what it looks like with the sidebar, file list, and preview all wired together:

Multi-Component Applications screenshot

Next Steps