ZigZag: a typed Model-Update-View TUI framework for Zig

The architecture is the argument

ZigZag brings typed Model-Update-View applications to the terminal with no third-party dependencies, and the architecture row of the feature table is the part worth understanding first, because it is what separates this from a collection of widgets. The pattern is the one popularised by Elm and adopted in various forms since, and the README summarises the loop in a single sentence, that events update the model and then view renders the next terminal frame. The flow diagram in the README makes the cycle explicit, with input, timers and async work feeding an update function, which produces a new model, which the view turns into a frame, which goes to the terminal, and the model can also emit a command that loops back to input. The interesting part for a Zig programmer is the typing. The framework is described as typed Model-Update-View, and given that the primary language is Zig and that the project carries a name with two Zs, the type system is doing real work here rather than being a marketing word. A terminal application that models its state as a tagged union and renders it through a pure view function has the property that the state transitions are checkable, and the framework is built around making that the default shape rather than an option.

Forty plus components, grouped by what you are building

The component list is the substance of the framework, and it is organised into five groups that map onto what people actually build. The input and forms group has text input, text area, checkbox, radio group, slider, dropdown, form, file picker and stepper. The data and navigation group has list, virtual list, table, sortable table, data table, tree, tabs, breadcrumbs and screen stacks, and the screen stacks entry is the one that tells you about navigation, since a stack of screens is how a TUI implements pushing and popping views. The visualisation group has progress, spinner, gauge, sparkline, chart, bar chart, heatmap, canvas and a Braille canvas, and the Braille canvas is a distinctive choice, since a Braille cell matrix gives you a plot at terminal resolution rather than at pixel resolution. The overlays and feedback group has modal, confirmation, tooltip, notification, toast, context menu and a command palette. The content and tooling group has Markdown, code view, diff view, rich log, status bar, help and a developer console. The developer console is worth flagging because it is the kind of component that only makes sense in a framework with a component model rather than in a bag of widgets, since it implies the framework can introspect its own state.

Styling, layout and the rendering strategy

Three rows of the feature table describe the parts that make a TUI pleasant rather than merely functional. Styling covers ANSI, 256-color and TrueColor, adaptive themes, borders and text overflow, and the adaptive themes entry implies the framework can follow or respond to a terminal colour scheme rather than forcing one palette. Layout covers placement, Flexbox constraints, split panes and layered composition, and Flexbox constraints is the significant one, because it is a way of expressing sizing relationships between a parent and its children rather than a fixed grid, which is what you need when a panel has to share space with something whose content length you do not control. Terminal support covers keyboard, mouse, clipboard, images and suspend and resume, and suspend and resume is the detail that separates a serious TUI from a demo, since a long-running program that cannot be suspended is a program you cannot run in a terminal multiplexer. The performance row lists diff rendering, ANSI compression and virtual lists, and those three together are the standard answer to the problem that a naive TUI redraws the whole screen on every keystroke. Diff rendering means only changed cells are written, ANSI compression means redundant escape sequences are collapsed, and a virtual list means a list of a million rows does not cost a million cells of memory.

Getting it into a build

The quick start requires Zig 0.16.0 or newer and is tested on 0.16 and 0.17, which the badge in the README header confirms. Adding the dependency is the standard Zig fetch.

zig fetch --save git+https://github.com/meszmate/zigzag#main

Then you wire the module into your build file, where the dependency is declared with a target and an optimize mode and the resulting module is added as an import.

const zigzag = b.dependency("zigzag", .{
    .target = target,
    .optimize = optimize,
});

exe.root_module.addImport("zigzag", zigzag.module("zigzag"));

The README points you at the counter example as the place to start, and that is the right instinct for a framework like this, because the counter is the smallest program that exercises the model, the update function, the view and the event loop, and reading it tells you the shape of an application before you write any of your own. The examples directory is extensive and listed in the repository tree, and the names alone indicate the coverage, with accessibility, action_system, animation, async_tasks, braille_canvas, calendar, charts, checkbox_radio, clipboard_osc52, code_view, context_menu, counter, dashboard, data_table, dev_console, diff_view, dropdown, file_browser, flex_layout, focus_form, form, gauge, heatmap, hello_world and layers among them. That list reads as a specification of what the framework can do, and the fact that accessibility and an action system have their own examples is a good sign for a library that is still young.

The runnable examples are the documentation

The README gives four demo commands and a pointer to the examples directory, and the commands are the fastest way to judge the framework. Four are named in the README, a component gallery, a dashboard, a file browser and a WebAssembly example, each with a build target of the form zig build run-<name>. The component gallery is the one to start with, since it exists to display the components in use, and the README header carries an animated image of it. The dashboard runs with zig build run-dashboard, the file browser with zig build run-file_browser and the WebAssembly example with zig build run-wasm_app. The file browser is the one to look at if you care about the framework handling real data, since a file browser is a layout problem with variable-length names and a scrolling list, which exercises the virtual list and the table components. The WebAssembly example is the most surprising, since it suggests the terminal rendering path is not tied to a native process, and if a browser-hosted terminal is a thing you care about, that example is the place to look. The README also points to a reference document with a component index, and to the examples directory as a whole, so the documentation strategy is example-led rather than prose-led, which suits a project where the API surface is wide and shallow.

Where ZigZag is the wrong tool

The first limit is maturity, and it is not a small one. The version is 0.1.7, which means the API is not settled and the components will move, and the release history is short with v0.1.5, v0.1.6 and v0.1.7 as recent entries, one of them titled for Zig 0.16 compatibility. For a library whose whole value is a large set of components, a 0.1 version means you may find that the table you needed was renamed between releases. The second limit is ecosystem. A TUI framework is only as good as its ecosystem of extensions and the number of applications built with it, and the projects section of the README lists one, zmenu, a simple Zig application launcher for GNU/Linux. One real consumer is a start, not a track record, and it means when you hit a component bug you are reading the framework's own source rather than asking a community. The third limit is scope, since a terminal interface is a small world compared with a graphical one, and features such as rich text, images in the terminal and a proper text editor are all things you will find only partially covered. The fourth is that the no-dependency stance cuts both ways, because it means there is no ready-made terminal handling, and you will spend effort on input edge cases that a mature library has already solved. The framework is young enough that it will keep changing, and the deciding question is whether you want to shape it or merely use it.

Editorial conclusion

Adopt ZigZag if you are writing a terminal application in Zig and want typed state, a large component set and layout primitives rather than hand-coding escape sequences and input parsing. Skip it if you need a mature, battle-tested TUI toolkit, since the version number is still 0.1 and the ecosystem is thin. Verify first that your Zig version is 0.16.0 or newer, that the components you need exist in the reference index rather than only in the demo gallery, and that a terminal feature you depend on, such as mouse reporting or clipboard access, is supported on the terminal you actually run.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. meszmate/zigzag on GitHub
4. README
5. Releases