GPUI Development
GPUI is a hybrid immediate/retained mode, GPU-accelerated UI framework for Rust from Zed.
Quick Reference
| Topic |
When to Use |
Reference |
| Fundamentals |
Starting new projects, understanding architecture |
fundamentals.md |
| State Management |
Entity, notify(), emit(), subscribe() |
state-management.md |
| Rendering |
div() API, layout, conditional rendering |
rendering.md |
| Actions |
Keyboard shortcuts, key bindings |
actions.md |
| Components |
gpui-component widgets (Button, Input, Table) |
components.md |
| Theming |
Colors, cx.theme(), Root view |
theming.md |
| Anti-patterns |
Common mistakes to avoid |
anti-patterns.md |
Critical Setup (MUST DO)
use gpui::{Application, App};
use gpui_component::Root;
fn main() {
Application::new().run(|cx: &mut App| {
gpui_component::init(cx); // REQUIRED when using gpui-component
cx.open_window(opts, |window, cx| {
let view = cx.new(|cx| MyView::new(window, cx));
cx.new(|cx| Root::new(view, window, cx)) // REQUIRED for theming
});
});
}
Key Mental Model (React vs GPUI)
| React |
GPUI |
Key Difference |
useState |
Struct fields + cx.notify() |
State in struct, manual re-render trigger |
| Component |
View (impl Render) |
Views are Entities that render |
| Virtual DOM |
GPU rendering |
No diffing - rebuild elements each frame |
| Props drilling |
Entity<T> handles |
Pass entity handles, not callbacks |
Instructions
REQUIRED: Before implementing GPUI code, load the relevant reference file(s) using the Read tool.
- Identify the task - What are you building?
- Load relevant references - Read the appropriate .md file(s) FIRST
- Follow patterns exactly - Use code patterns from references
- Check anti-patterns - Read anti-patterns.md before writing code
Reference Selection Guide
- New project setup → Read fundamentals.md FIRST
- Managing state, events → Read state-management.md FIRST
- Building UI layouts → Read rendering.md FIRST
- Adding keyboard shortcuts → Read actions.md FIRST
- Using Button, Input, Select, Table → Read components.md FIRST
- Styling, colors, themes → Read theming.md FIRST
- Debugging issues → Read anti-patterns.md FIRST
Cargo.toml
[dependencies]
gpui = "0.2.2"
gpui-component = "0.6.0-preview0"
Common Patterns
State Update Pattern
impl MyView {
fn update_something(&mut self, cx: &mut Context<Self>) {
self.value = new_value;
cx.notify(); // ALWAYS call after state changes
}
}
Button Click Pattern
Button::new("btn-id")
.label("Click Me")
.on_click(|_, _, cx| {
// handle click
})
Stateful Component Pattern
struct MyView {
input: Entity<InputState>, // Store entity in struct
}
impl MyView {
fn new(window: &Window, cx: &mut Context<Self>) -> Self {
Self {
input: cx.new(|cx| InputState::new(window, cx)), // Create once
}
}
}
1---2name: gpui3description: Build desktop apps with GPUI, the GPU-accelerated UI framework from Zed. Covers Entity state, Render trait, div() Tailwind API, actions/keybindings, gpui-component widgets, theming. Use when building Rust desktop applications with GPUI or gpui-component.4---5
6# GPUI Development
7
8GPUI is a hybrid immediate/retained mode, GPU-accelerated UI framework for Rust from Zed.
9
10## Quick Reference
11
12| Topic | When to Use | Reference |
13|-------|-------------|-----------|
14| **Fundamentals** | Starting new projects, understanding architecture | [fundamentals.md](fundamentals.md) |
15| **State Management** | Entity<T>, notify(), emit(), subscribe() | [state-management.md](state-management.md) |
16| **Rendering** | div() API, layout, conditional rendering | [rendering.md](rendering.md) |
17| **Actions** | Keyboard shortcuts, key bindings | [actions.md](actions.md) |
18| **Components** | gpui-component widgets (Button, Input, Table) | [components.md](components.md) |
19| **Theming** | Colors, cx.theme(), Root view | [theming.md](theming.md) |
20| **Anti-patterns** | Common mistakes to avoid | [anti-patterns.md](anti-patterns.md) |
21
22## Critical Setup (MUST DO)
23
24```rust
25use gpui::{Application, App};
26use gpui_component::Root;
27
28fn main() {
29 Application::new().run(|cx: &mut App| {
30 gpui_component::init(cx); // REQUIRED when using gpui-component
31
32 cx.open_window(opts, |window, cx| {
33 let view = cx.new(|cx| MyView::new(window, cx));
34 cx.new(|cx| Root::new(view, window, cx)) // REQUIRED for theming
35 });
36 });
37}
38```
39
40## Key Mental Model (React vs GPUI)
41
42| React | GPUI | Key Difference |
43|-------|------|----------------|
44| `useState` | Struct fields + `cx.notify()` | State in struct, manual re-render trigger |
45| Component | View (impl `Render`) | Views are Entities that render |
46| Virtual DOM | GPU rendering | No diffing - rebuild elements each frame |
47| Props drilling | `Entity<T>` handles | Pass entity handles, not callbacks |
48
49## Instructions
50
51**REQUIRED**: Before implementing GPUI code, load the relevant reference file(s) using the Read tool.
52
531. **Identify the task** - What are you building?
542. **Load relevant references** - Read the appropriate .md file(s) FIRST
553. **Follow patterns exactly** - Use code patterns from references
564. **Check anti-patterns** - Read [anti-patterns.md](anti-patterns.md) before writing code
57
58### Reference Selection Guide
59
60- **New project setup** → Read [fundamentals.md](fundamentals.md) FIRST
61- **Managing state, events** → Read [state-management.md](state-management.md) FIRST
62- **Building UI layouts** → Read [rendering.md](rendering.md) FIRST
63- **Adding keyboard shortcuts** → Read [actions.md](actions.md) FIRST
64- **Using Button, Input, Select, Table** → Read [components.md](components.md) FIRST
65- **Styling, colors, themes** → Read [theming.md](theming.md) FIRST
66- **Debugging issues** → Read [anti-patterns.md](anti-patterns.md) FIRST
67
68## Cargo.toml
69
70```toml
71[dependencies]
72gpui = "0.2.2"
73gpui-component = "0.6.0-preview0"
74```
75
76## Common Patterns
77
78### State Update Pattern
79
80```rust
81impl MyView {
82 fn update_something(&mut self, cx: &mut Context<Self>) {
83 self.value = new_value;
84 cx.notify(); // ALWAYS call after state changes
85 }
86}
87```
88
89### Button Click Pattern
90
91```rust
92Button::new("btn-id")
93 .label("Click Me")
94 .on_click(|_, _, cx| {
95 // handle click
96 })
97```
98
99### Stateful Component Pattern
100
101```rust
102struct MyView {
103 input: Entity<InputState>, // Store entity in struct
104}
105
106impl MyView {
107 fn new(window: &Window, cx: &mut Context<Self>) -> Self {
108 Self {
109 input: cx.new(|cx| InputState::new(window, cx)), // Create once
110 }
111 }
112}
113```
majiayu000