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.
• GPUI from the pinned Zed revision below.
• Platform tooling: Xcode on macOS; Wayland/X11 dev packages on Linux; nothing extra on Windows.

Add the dependency

Clone this repository and add the source dependency with the matching GPUI revision to Cargo.toml:

1[dependencies]
2gpui = { git = "https://github.com/zed-industries/zed", rev = "ee3b5558c581429633937e458fad8d109f29e9ee" }
3gpui_platform = { git = "https://github.com/zed-industries/zed", rev = "ee3b5558c581429633937e458fad8d109f29e9ee", features = ["font-kit", "wayland", "x11", "runtime_shaders"] }
4herogpui = { path = "../HeroGPUI/crates/herogpui" }

Your first window

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

1use gpui::*;
2use herogpui::prelude::*;
3
4struct MyRoot;
5
6impl Render for MyRoot {
7    fn render(&mut self, window: &mut Window, cx: &mut Context<Self>) -> impl IntoElement {
8        app_focus_root(
9            div().size_full().bg(cx.colors().background).text_color(cx.colors().foreground),
10            window,
11            cx,
12        )
13    }
14}
15
16fn main() {
17    gpui_platform::application().with_assets(HeroGpuiAssets).run(|cx: &mut App| {
18        ThemeProvider::init(cx); // light + dark
19        // or ThemeProvider::init_with(Theme::dark(), cx);
20        let bounds = Bounds::centered(None, size(px(1280.), px(820.)), cx);
21        cx.open_window(WindowOptions { window_bounds: Some(WindowBounds::Windowed(bounds)), ..Default::default() },
22            |_, cx| cx.new(|_| MyRoot)).unwrap();
23    });
24}

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 gpui_platform::application().with_assets(HeroGpuiAssets). Apps that bring their own assets use HeroGpuiAssets::with_fallback(MyAppAssets) so both are served.

ThemeProvider::init(cx) 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.

1cargo build                     # builds library + gallery
2cargo 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