Zeichenwerk Tutorial

May 15, 2026 · View on GitHub

A guided tour of building terminal UIs with zeichenwerk, from a 20-line "hello world" to a working SQLite query tool.

Who this is for

Go developers who want to build interactive terminal applications without hand-rolling a tcell event loop, focus engine, layout system, and rendering pipeline. No prior TUI experience required; basic Go familiarity is assumed.

What you'll build

By the end of this tutorial you'll have written:

  • A handful of small example programs (one per concept).
  • A real SQLite query tool with a schema list, SQL editor, and result table — the kind of app you'd actually keep in your toolbelt.

How to read this

Each chapter is a single Markdown file. Every code snippet you see is also shipped as a runnable Go program under examples/ — clone the repo and run them as you go.

go run ./examples/01-teaser
go run ./examples/03-layout-flex
go run ./examples/09-sqlite/step-5-wired

Press q or Ctrl-Q to quit any example.

API choice

The tutorial uses the Builder API throughout. zeichenwerk also ships a functional compose API that produces equivalent UIs; the patterns transfer one-to-one. Pick whichever style fits your taste once you know the framework.

Table of contents

Part I — Teaser

  1. A TUI in 20 lines — what a minimal app looks like and what the framework does for you.

Part II — Concepts

  1. Architecture & lifecycle — the four layers, frame pipeline, and the build-then-wire pattern.
  2. Layout — Flex, Grid, and Hint semantics.
  3. Styling & themes — theme variables, selectors, classes.
  4. Events & focus — handlers, focus traversal, redraw vs. relayout.

Part III — Widgets in depth

  1. Widget tour — quick catalog of every widget.
  2. Containers — Switcher, Tabs, Forms, Dialogs.
  3. Custom widgets — extending Component with your own render code.

Part IV — Real-world example

  1. Building a SQLite query tool — a full application, six incremental steps.

Appendices

Prerequisites

go get github.com/tekugo/zeichenwerk

Go 1.26+ is required. The SQLite tutorial additionally needs mattn/go-sqlite3 (pulled in automatically when you run that example).

Where to go from here