zgui

Installation

Add zgui to a Cargo project, install the system libraries a window needs, and open your first window.

zgui is published on crates.io and builds on stable Rust 1.90 or later. Getting a window on screen takes three steps: add the crate, install the system libraries (Linux only), and run a small program.

Create a project

cargo new my-app
cd my-app
cargo add zgui

Your Cargo.toml now depends on zgui:

Cargo.toml
[dependencies]
zgui = "0.1"

zgui is the only crate most applications need. It re-exports the document, styling, layout, text, rendering, and platform layers. Optional crates and features lists the extras.

Install system libraries

Linux

Install the development headers for Wayland, X11, xkbcommon, and fontconfig:

sudo apt-get install -y --no-install-recommends \
  pkg-config libx11-dev libxkbcommon-dev libxkbcommon-x11-dev \
  libwayland-dev libxcb1-dev libxcursor-dev libxi-dev libxrandr-dev \
  libfontconfig1-dev

You also need a working Vulkan or OpenGL driver. Mesa's software rasteriser works on machines without a GPU.

macOS and Windows

No extra libraries. Use the standard Rust toolchain with Xcode's command line tools on macOS, or the MSVC build tools on Windows. zgui draws with Metal on macOS and Direct3D 12 (with OpenGL as a fallback) on Windows.

Open a window

src/main.rs
use zgui::prelude::*;

fn main() -> Result<(), zgui::Error> {
    app()
        .with_title("Hello")
        .with_size(480.0, 320.0)
        .with_stylesheet(css!(
            ":root {
                background-color: #12141a;
                color: #e8ecf4;
                font-family: sans-serif;
                display: flex;
                align-items: center;
                justify-content: center;
            }
            .hello { font-size: 32px; font-weight: 700; }"
        ))
        .run(|| view! { text(class = "hello") {"Hello"} })
}
cargo run

A window opens with "Hello" in white on a dark background. app() starts the application builder, run opens the window and returns when the application exits, and the closure passed to run builds the window's content. Your first application explains each part in detail.

Optional crates and features

Add other crates only when you need them:

CrateWhen to add it
zgui-ui, zgui-ui-tokensYou want the component library and its themes.
zgui-ui-iconsYou want the library's icon set.
zgui-imageYou register encoded image bytes from memory. File paths need only zgui.
zgui-testkit-view, zgui-platform-headlessHeadless tests, as [dev-dependencies]. See Testing.

The zgui crate has one feature an application is likely to want: tokio, which runs background work on a tokio runtime so tasks can await tokio timers and sockets.

zgui = { version = "0.1", features = ["tokio"] }

Speed up font lookup

The zgui repository patches fontique, the font collection under the text engine, so that it reuses resolved font families between paragraphs. A crates.io build uses the released fontique: text looks the same, but font resolution is slower. This step is optional. To use the patched copy, add this to your application's Cargo.toml:

Cargo.toml
[patch.crates-io]
fontique = { git = "https://github.com/zortax/zgui", tag = "v0.1.0" }

Choose a platform or graphics backend

zgui picks the platform and graphics backend automatically. You can override the choice with environment variables, which helps when you diagnose a driver or compositor problem.

VariableValuesEffect
ZGUI_PLATFORMwayland, winitLinux and BSD only. By default zgui uses its native Wayland backend when a Wayland compositor is available, and winit otherwise (X11). winit forces the portable backend, including on Wayland. wayland requires the native backend and returns an error if it cannot connect.
ZGUI_BACKENDSvulkan, metal, dx12, gl, all, none; comma-separatedRestricts which graphics APIs are tried. Defaults: Metal on Apple platforms, Direct3D 12 then OpenGL on Windows, Vulkan then OpenGL elsewhere.
ZGUI_DEVICE_IDPCI device id, decimal or 0x hexPrefers one GPU over the others.
ZGUI_BACKENDS=vulkan cargo run

Shipping describes device selection in full. Tests need neither a display server nor a GPU: the headless backend draws into memory. See Testing.

Run the examples

The zgui repository has working examples in examples/. Clone it and run one with Cargo:

git clone https://github.com/zortax/zgui
cd zgui
cargo run -p zgui-examples --example counter
ExampleShows
counterSignals, a reactive text node, click listeners
todoA keyed list, keyboard text input, per-row state
tallyA small application written only against the prelude
styledWhat the style engine draws: borders, gradients, shadows, filters
resizeLayout while the window is being resized
asyncBackground work and cancellation
windowsSeveral windows sharing state
csdA window that draws its own title bar and frame
imagesImages, object-fit, and sampling (set ZGUI_IMAGES_DIR to a folder with photo.png and portrait.png)
vectorVector outlines and SVG on vector elements
canvasImperative drawing on a canvas element
customA custom element implemented in Rust
shaderAn application shader written in WGSL
surfaceEmbedding pixels from another wgpu renderer

Add --release for the graphics-heavy examples (canvas, vector, custom, shader, surface, resize). The component gallery is in the zgui-ui crate:

cargo run -p zgui-ui --example gallery

The repository pins a nightly toolchain in rust-toolchain.toml, and rustup installs it automatically inside the checkout. Only work on zgui itself needs nightly; your own projects use stable.

Next

On this page