Installation

New to the library? Use Quick Start to get a button on screen, then come back here for assets, the gallery CLI, and platform notes.

Prerequisites

• A Rust toolchain that supports Rust 1.98.
• Nothing else: herogpui depends on the published gpui-pre GPUI crates and re-exports them.
• Platform tooling: Xcode on macOS; Wayland/X11 dev packages on Linux; nothing extra on Windows.

Add the dependency

herogpui is published on crates.io. Add it as your one dependency — it is a facade over the GPUI crate family, so use herogpui::*; is GPUI and herogpui::application() opens the platform:

1
2[dependencies]
herogpui = "0.14"

Do not add gpui or gpui_platform to your own Cargo.toml — a second copy of GPUI is how versions drift apart. This release carries GPUI 0.3.5. Zed does not publish gpui under that name, so GPUI arrives as gpui-pre, a prerelease publish of the Zed GPUI sources by crates.io user huacnlee (the gpui-kit maintainer), pinned exactly; the unrelated crates.io gpui 0.2.2 crate is a different library and will not compile against this one.

Each layer is a Cargo feature and a named path: herogpui::components (the components feature, on by default), herogpui::theme (theme), herogpui::core (core), and herogpui::platform, which is always present. test-support and profiler forward the same-named GPUI features. serde is off by default and forwards herogpui-theme/serde for sparse ThemeDocument JSON. On wasm32, herogpui::web is the same platform layer.

Your first window

Register the embedded assets and theme provider, open a window, and wrap its root in app_focus_root:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23use herogpui::*;

struct MyRoot;

impl Render for MyRoot {
    fn render(&mut self, window: &mut Window, cx: &mut Context<Self>) -> impl IntoElement {
        app_focus_root(
            div().size_full().bg(cx.colors().background).text_color(cx.colors().foreground),
            window,
            cx,
        )
    }
}

fn main() {
    application().with_assets(HeroGpuiAssets).run(|cx: &mut App| {
        herogpui::init(cx); // = ThemeProvider::init(cx), light + dark
        // or ThemeProvider::init_with(Theme::dark(), cx);
        let bounds = Bounds::centered(None, size(px(1280.), px(820.)), cx);
        cx.open_window(WindowOptions { window_bounds: Some(WindowBounds::Windowed(bounds)), ..Default::default() },
            |_, cx| cx.new(|_| MyRoot)).unwrap();
    });
}

What the pieces are

HeroGpuiAssets embeds the herogpui/icons/*.svg files used by built-in component chrome — checkmarks, chevrons, the clear button. Register it with application().with_assets(HeroGpuiAssets). Apps that bring their own assets use HeroGpuiAssets::with_fallback(MyAppAssets) so both are served.

herogpui::init(cx) initializes every enabled layer. Today that is ThemeProvider::init(cx), which registers the provider with both the light and dark themes, and must run before the first window opens — rendering a themed component before initialization panics. Start dark with ThemeProvider::init_with(Theme::dark(), cx).

app_focus_root(root, window, cx) wraps the window's root element to enable Tab traversal, focus-visible state and root capture handlers. Without it, focus-visible rings and keyboard movement across components do not work.

Finally, set the root background and text color from the tokens, and your font family — GPUI does not inherit one for you:

1div().bg(cx.colors().background).text_color(cx.colors().foreground).font_family("Segoe UI")

Run the gallery

The gallery is the library's desktop documentation: one page per component, 15 categories, runnable examples and a theme switcher. The Gallery guide covers deep links and the installed CLI.

1
2cargo build                     # builds library + gallery
cargo run -p herogpui-gallery   # open the component gallery

It opens as a 1280×820 window. Two environment variables pick the page and the appearance, which is also how the screenshots that gate the visual regressions are captured.HEROGPUI_WINDOW_SIZE=1200x2000 overrides the size:

1HEROGPUI_PAGE="Button" HEROGPUI_THEME=dark cargo run -p herogpui-gallery