Introduction

What you install

gpuicn is a set of 60 components for GPUI. Visually they follow shadcn/ui. Behaviorally they use GPUI Kit, which supplies pointer, keyboard, and accessibility handling on top of GPUI's renderer. A Dialog traps focus and a Slider reads arrow keys. Neither behavior is implemented in gpuicn's own files.

You do not depend on gpuicn at runtime. The CLI copies a component's Rust module into your crate, where it compiles against the same gpui_kit types your own views use. The module is yours after that. Updates never touch it unless you ask with --overwrite.

This is the Usage example for Button, which is the whole public API a view needs:

use crate::ui::button::Button;
use gpui_kit::IntoElement;

fn example() -> impl IntoElement {
    Button::new("open-docs")
        .on_click(|_, _, cx| cx.open_url("https://ui.imajha.com"))
        .label("Open docs")
}

Source or crate

There are two ways to use the catalog. They are meant to be combined.

Installed source is the default. gpuicn add writes modules under src/ui and keeps src/ui/mod.rs current. Every change you make is a normal commit in your repository, reviewed like any other code.

The gpuicn crate compiles the same registry behind one Cargo dependency. It suits an app that wants the whole catalog without files to maintain. When you need to change one component, eject it. The ejected file is the same source the crate was built from.

How to read a component chapter

Each of the 60 component chapters has the same five parts.

1. A numbered figure that runs the component. The preview is the component itself, compiled to WebAssembly, so you can test the behavior before you install it.
2. Installation, which gives the command and the module declarations the CLI maintains.
3. Usage, a compile-checked example to paste into a view.
4. API reference, every public function in the installed file, generated from the source.
5. Platform notes, which record where behavior on this GPUI revision differs from the browser original, including accessibility limits.

What this book assumes

You can read Rust and have built a GPUI window before. The Installation chapter is a how-to, not a tutorial. It names each file it writes and what you should see, but it does not explain GPUI's context or entity model. For that, read GPUI's own documentation.

gpuicn is experimental. Component APIs and visuals change between releases, and a release may change installed source in ways a --dry-run shows before you accept them. Pin one release, and read the release notes before moving to the next.