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 zguiYour Cargo.toml now depends on zgui:
[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-devYou 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
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 runA 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:
| Crate | When to add it |
|---|---|
zgui-ui, zgui-ui-tokens | You want the component library and its themes. |
zgui-ui-icons | You want the library's icon set. |
zgui-image | You register encoded image bytes from memory. File paths need only zgui. |
zgui-testkit-view, zgui-platform-headless | Headless 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:
[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.
| Variable | Values | Effect |
|---|---|---|
ZGUI_PLATFORM | wayland, winit | Linux 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_BACKENDS | vulkan, metal, dx12, gl, all, none; comma-separated | Restricts which graphics APIs are tried. Defaults: Metal on Apple platforms, Direct3D 12 then OpenGL on Windows, Vulkan then OpenGL elsewhere. |
ZGUI_DEVICE_ID | PCI device id, decimal or 0x hex | Prefers one GPU over the others. |
ZGUI_BACKENDS=vulkan cargo runShipping 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| Example | Shows |
|---|---|
counter | Signals, a reactive text node, click listeners |
todo | A keyed list, keyboard text input, per-row state |
tally | A small application written only against the prelude |
styled | What the style engine draws: borders, gradients, shadows, filters |
resize | Layout while the window is being resized |
async | Background work and cancellation |
windows | Several windows sharing state |
csd | A window that draws its own title bar and frame |
images | Images, object-fit, and sampling (set ZGUI_IMAGES_DIR to a folder with photo.png and portrait.png) |
vector | Vector outlines and SVG on vector elements |
canvas | Imperative drawing on a canvas element |
custom | A custom element implemented in Rust |
shader | An application shader written in WGSL |
surface | Embedding 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 galleryThe 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.