Knots documentation
Build GUI apps in Zig. #
Knots is a cross-platform, immediate-mode GUI library for Zig. You write the interface as Zig code. The same code runs on macOS, Windows, Linux, and in the browser.
Getting started #
Install Zig, add Knots to a project, and open a first window.
Tutorial: a todo app #
Go from zig init to a complete todo app, step by step.
Components #
See every built-in component and how to make your own.
Styles and themes #
Change colors, sizes, and states with one style type.
Layout engine #
Learn how Knots sizes and places each element.
Best practices #
Avoid state bugs and keep frames fast.
Hot reloading #
Change UI code and see the result without a restart.
How Knots works #
Knots is an immediate-mode library. Your code describes the full interface each frame. Knots does not keep a tree of widget objects for you to change. When your data changes, you describe the interface again.
Each frame has four stages:
- The host collects input: pointer, keys, text, and window size.
- Your frame function emits components into a
ui.Frame. - Knots calculates layout, resolves styles, and handles interaction.
-
Knots produces a
render.Packetand a set of effects. A GPU backend draws the packet.
Knots keeps some state between frames, for example focus, scroll position, and text selection. It finds this state with a key that you give to each component. Your application data stays in your own variables.
Choose an integration path #
| Path | Use it when |
|---|---|
knots.App |
Knots must own the window, the event loop, and the renderer. This is the usual path. Start with Getting started. |
ui.Context + render.Packet |
Your program already has a window or a GPU renderer, for example a game engine. Read Embedding. |
Both paths use the same components and produce the same output.
Modules #
The Knots package exports several Zig modules. Most applications import only
knots and ui.
| Module | Contents |
|---|---|
knots |
App, View, platform, web,
debug, and NativeAccessibility.
|
ui |
Frame, Context, component,
control, Style, Theme, Key,
and Accessibility.
|
input |
The input types that a host gives to ui.Context.beginFrame. |
render |
The API-neutral Packet that a frame produces. |
renderer |
The bundled GPU renderer: Renderer and Painter. |
window, gpu, math |
The native window, the GPU abstraction, and math types. |
Platform support #
| Platform | Default backend | Other backends |
|---|---|---|
| macOS | WebGPU | Vulkan (MoltenVK) |
| Windows | Vulkan | WebGPU |
| Linux (Wayland) | Vulkan | WebGPU |
Browser (wasm32-freestanding) |
WebGPU | None |
Read GPU backends to select a backend.
Known limits. Linux windows use Wayland only. There is no X11 support. Text uses one glyph for each Unicode codepoint. Knots does not do complex shaping, bidirectional text, ligatures, font fallback, or IME composition. Read Text and fonts for details.