Glyph

glyph

Declarative terminal UI framework for Go. Always refer to useglyph.sh/api for the full API reference before assuming an API does not exist.

Use dot-import:

import . "github.com/kungfusheep/glyph"

How glyph works

You declare a view tree once. glyph compiles it to a template. Every frame, it dereferences your pointers to read current state.

Rules:

• Call SetView or app.View() once. Never in a loop.
• Bind dynamic values with pointers (&name, &items)
• Mutate the pointed-to value, then call app.RequestRender() from goroutines (handlers auto-render)
• Use If/Switch/ForEach inside the tree for conditional/dynamic content, not Go control flow around SetView

Guidelines for writing glyph code

Use the functional API, not the struct API glyph has two APIs: a legacy struct API (VBoxNode{Children: []any{...}}, TextNode{Content: &name}) and the current functional API (VBox(children...), Text(&name).Bold()). Always use the functional API. The struct types still exist in the package but are no longer idiomatic.

// wrong: struct API
VBoxNode{Children: []any{TextNode{Content: &name}}}

// correct: functional API
VBox(Text(&name))

Use text alignment styles Instead of manually padding strings, use Style{Align: AlignCenter} or Style{Align: AlignRight} with a fixed-width container:

Text("centered").Style(Style{Align: AlignCenter}).Width(40)
Text("right-aligned").Style(Style{Align: AlignRight}).Width(40)

Complete example: single-view app

package main

import (
    "fmt"
    "log"
    "time"
    . "github.com/kungfusheep/glyph"
)

func main() {
    app, err := NewApp()
    if err != nil {
        log.Fatal(err)
    }

    count := 0
    countLabel := "0"
    frame := 0
    status := "ready"

    app.SetView(
        VBox.Border(BorderRounded).Title("Demo")(
            HBox.Gap(2)(
                Text("Count:"),
                Text(&countLabel).Bold().FG(Cyan),
                Spinner(&frame).Frames(SpinnerDots),
            ),
            Progress(&count).Width(30).FG(Green),
            If(&status).Eq("done").
                Then(Text("Complete!").FG(Green)).
                Else(Text(&status).Dim()),
        ),
    )

    app.Handle("j", func() { count++; countLabel = fmt.Sprintf("%d", count) })
    app.Handle("k", func() { count--; countLabel = fmt.Sprintf("%d", count) })
    app.Handle("q", app.Stop)

    go func() {
        for range time.Tick(80 * time.Millisecond) {
            frame++
            app.RequestRender()
        }
    }()

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

Complete example: multi-view app with form

package main

import (
    "fmt"
    "log"
    "time"
    . "github.com/kungfusheep/glyph"
)

func main() {
    app, err := NewApp()
    if err != nil {
        log.Fatal(err)
    }

    // form state
    var name string
    var target int

    // deploy state
    steps := []string{"Build", "Test", "Deploy", "Verify"}
    activeStep := ""
    progress := 0
    progressLabel := "0%"
    frame := 0
    logs := []string{}
    showError := false

    // named func; reused from submit and retry handlers
    deploy := func() {
        progress = 0
        progressLabel = "0%"
        logs = nil
        showError = false
        app.RequestRender()
        go func() {
            for i, step := range steps {
                activeStep = step
                app.RequestRender()
                time.Sleep(500 * time.Millisecond)
                if i == 2 {
                    logs = append(logs, "ERROR: health check failed")
                    showError = true
                    app.RequestRender()
                    return
                }
                progress = (i + 1) * 25
                progressLabel = fmt.Sprintf("%d%%", progress)
                logs = append(logs, fmt.Sprintf("%s complete", step))
                app.RequestRender()
            }
            progress = 100
            progressLabel = "100%"
            logs = append(logs, "deployment complete!")
            app.RequestRender()
        }()
    }

    var form *FormC
    form = Form.LabelBold().OnSubmit(func() {
        if form.ValidateAll() {
            app.Go("main")
            deploy()
        }
    })(
        Field("Name", Input(&name).Placeholder("release name").Validate(VRequired)),
        Field("Target", Radio(&target, "staging", "production")),
    )

    app.View("form",
        VBox.Border(BorderRounded).Title("Config")(form),
    ).NoCounts().Handle("q", app.Stop)

    app.View("main",
        VBox.Gap(1)(
            HBox.Gap(1)(
                // ForEach with conditional per-item rendering:
                // compare external state pointer against each item
                VBox.WidthPct(0.3).Border(BorderRounded).Title("Steps")(
                    ForEach(&steps, func(step *string) any {
                        return If(&activeStep).Eq(*step).
                            Then(HBox.Gap(1)(
                                Spinner(&frame).Frames(SpinnerDots).FG(Cyan),
                                Text(step).Bold(),
                            )).
                            Else(Text(step).Dim())
                    }),
                ),
                VBox.WidthPct(0.4).Border(BorderRounded).Title("Progress")(
                    Text(&progressLabel).Bold(),
                    Progress(&progress).FG(Green),
                ),
                VBox.WidthPct(0.3).Border(BorderRounded).Title("Log")(
                    ForEach(&logs, func(line *string) any {
                        return Text(line).Dim()
                    }),
                ),
            ),
            If(&showError).Then(
                Overlay.Centered().Backdrop().BackdropFG(BrightBlack)(
                    VBox.Border(BorderRounded).Title("Error")(
                        Text("Failed at 75%").FG(Red),
                        Text("[r] retry  [c] cancel").Dim(),
                    ),
                ),
            ),
        ),
    ).Handle("q", app.Stop).
        Handle("r", func() { if showError { showError = false; deploy() } }).
        Handle("c", func() { if showError { showError = false; app.Go("form") } })

    // spinner animation; always running
    go func() {
        for range time.Tick(80 * time.Millisecond) {
            frame++
            app.RequestRender()
        }
    }()

    if err := app.RunFrom("form"); err != nil {
        log.Fatal(err)
    }
}

Complete example: inline prompt

Input() without a pointer returns an *InputC. Read the value after Run() via .Value().

package main

import (
    "fmt"
    "log"
    . "github.com/kungfusheep/glyph"
)

func main() {
    name := Input().Placeholder("your name").Width(30)
    token := Input().Placeholder("ghp_...").Width(30).Mask('*')

    app, err := NewInlineApp()
    if err != nil {
        log.Fatal(err)
    }

    app.ClearOnExit(true).
        SetView(Form.LabelFG(Cyan)(
            Field("Name", name),
            Field("Token", token),
        )).
        Handle("<Enter>", app.Stop).
        Handle("<Escape>", app.Stop)

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

    fmt.Printf("name=%q token=%q\n", name.Value(), token.Value())
}

Pitfalls

API reference

App

Layout

Border styles: BorderRounded, BorderSingle, BorderDouble.

Display

Text only accepts string or *string. To display a number, format it: label := fmt.Sprintf("%d%%", pct) then Text(&label).

Spinner frame sets: SpinnerBraille, SpinnerDots, SpinnerLine, SpinnerCircle. Tab styles: TabsStyleUnderline, TabsStyleBox, TabsStyleBracket.

String display helpers return string. Use inside Text() or format into a *string:

Lists

FilterList query syntax: foo fuzzy, 'exact, ^prefix, suffix$, !negate, a b AND, a | b OR.

CheckList struct tags: tag struct fields and glyph resolves .Checked() and .Render() from them:

type Task struct {
    Name    string `glyph:"render"`
    Done    bool   `glyph:"checked"`
}

CheckList(&tasks)  // render and checked resolved via struct tags

Without struct tags, configure manually: .Render(func(t *Task) any { return Text(&t.Name) }) and .Checked(func(t *Task) *bool { return &t.Done }).

.Ref() captures a component handle at build time:

var myList *ListC[Item]
List(&items).Render(fn).Ref(func(l *ListC[Item]) { myList = l })

.Ref() is available on List, CheckList, FilterList, Log, FilterLog, Input, Checkbox, Radio, and App/ViewBuilder.

Tables

Column formatters: Number(decimals), Percent(decimals), Currency(symbol, decimals), PercentChange(decimals), Bytes(), Bool(yes, no).

Forms

Validators: VRequired, VEmail, VMinLen(n), VMaxLen(n), VMatch(regex), VTrue. Trigger flags: VOnChange, VOnBlur, VOnSubmit.

TextInput outside forms. Use TextInput + app.BindField() for standalone text input:

var field InputState

app.BindField(&field)  // routes unmatched keystrokes to this field

// in view tree:
TextInput{Field: &field, Placeholder: "search..."}

InputState bundles Value string and Cursor int. Call field.Clear() to reset. For multiple focusable fields share a FocusGroup and set FocusIndex on each TextInput.

Conditionals

IfOrd operators: .Gt(), .Lt(), .Gte(), .Lte(), .Eq(), .Ne().

Switch requires .End() when it is not the last child in a container; omitting it is a compile error.

Styling

Colors: Black Red Green Yellow Blue Magenta Cyan White (and Bright variants), PaletteColor(0-255), RGB(r,g,b), Hex(0xRRGGBB), LerpColor(a, b, t).

Style struct: Style{FG: c, BG: c, Fill: c, Attr: AttrBold | AttrItalic, Align: AlignCenter}.

Attributes: AttrBold, AttrDim, AttrItalic, AttrUnderline, AttrInverse, AttrStrikethrough.

CascadeStyle applies a style to a container. Children inherit it and can override:

theme := Style{FG: Cyan}
VBox.CascadeStyle(&theme)(children...)

Built-in themes: ThemeDark, ThemeLight, ThemeMonochrome.

Key binding patterns

"q"          single key
"gg"         sequence
"<Enter>"    special key
"<C-c>"      ctrl+c
"<S-Tab>"    shift+tab
"<Up>"       arrow key

Special keys: <Enter>, <Escape>, <Tab>, <S-Tab>, <Space>, <Backspace>, <Delete>, <Up>, <Down>, <Left>, <Right>, <PageUp>, <PageDown>, <Home>, <End>, <C-x> (ctrl), <S-x> (shift), <A-x> (alt).

Advanced

Check useglyph.sh/api for anything not listed here.