gpui

GPUI Best Practices

Comprehensive guide for building desktop applications with GPUI, the UI framework powering Zed editor. Contains 40+ rules across 8 categories, prioritized by impact.

When to Apply

Reference these guidelines when:

• Writing new GPUI views or components
• Implementing state management with Entity
• Handling events and keyboard shortcuts
• Working with async tasks and background work
• Building forms, lists, or dialogs
• Styling components with Tailwind-like API
• Testing GPUI applications

Rule Categories by Priority

Priority	Category	Impact	Prefix
1	Core Concepts	CRITICAL	core-
2	Rendering	CRITICAL	render-
3	State Management	HIGH	state-
4	Event Handling	HIGH	event-
5	Async & Concurrency	MEDIUM-HIGH	async-
6	Styling	MEDIUM	style-
7	Components	MEDIUM	comp-
8	Anti-patterns	CRITICAL	anti-

Quick Reference

1. Core Concepts (CRITICAL)

• core-ownership-model - Understand GPUI's single ownership model
• core-entity-operations - Use read/update/observe/subscribe correctly
• core-weak-entity - Use WeakEntity to break circular references
• core-context-types - Know when to use App, Context, AsyncApp

2. Rendering (CRITICAL)

• render-render-vs-renderonce - Choose Render for stateful, RenderOnce for components
• render-element-composition - Build element trees with div() and method chaining
• render-conditional - Use .when() and .when_some() for conditional styling
• render-shared-string - Use SharedString to avoid string copying
• render-builder-pattern - Design components with builder pattern

3. State Management (HIGH)

• state-notify - Always call cx.notify() after state changes
• state-observe - Use cx.observe() to react to Entity changes
• state-subscribe - Use cx.subscribe() for typed events
• state-global - Use Global trait for app-wide state
• state-keyed-state - Use window.use_keyed_state() for persistent state

4. Event Handling (HIGH)

• event-actions - Define and register actions for keyboard shortcuts
• event-listener - Use cx.listener() for view-bound event handlers
• event-focus - Manage focus with FocusHandle and key_context
• event-propagation - Understand event bubbling and stop_propagation

5. Async & Concurrency (MEDIUM-HIGH)

• async-task-lifecycle - Store or detach tasks to prevent cancellation
• async-debounce - Implement debounce with timer + task replacement
• async-background-spawn - Use background_spawn for CPU-intensive work
• async-weak-entity - Use WeakEntity for safe cross-await access
• async-error-handling - Use .log_err() and .detach_and_log_err()

6. Styling (MEDIUM)

• style-flexbox - Use h_flex() and v_flex() for layouts
• style-theme-colors - Always use cx.theme() for colors
• style-spacing - Use DynamicSpacing for responsive spacing
• style-elevation - Use elevation system for layered surfaces

7. Components (MEDIUM)

• comp-stateless - Prefer RenderOnce with #[derive(IntoElement)]
• comp-traits - Implement Disableable, Selectable, Sizable traits
• comp-focus-ring - Add focus ring for accessibility
• comp-dialog - Use WindowExt for dialog management
• comp-variant - Use variant enums for component styles

8. Anti-patterns (CRITICAL)

• anti-silent-error - Never silently discard errors with let _ =
• anti-drop-task - Never drop Task without storing or detaching
• anti-drop-subscription - Always detach or store subscriptions
• anti-circular-reference - Avoid Entity cycles, use WeakEntity
• anti-missing-notify - Never forget cx.notify() after state changes
• anti-unwrap - Avoid unwrap(), use ? or explicit handling

Architecture Overview

┌─────────────────────────────────────────────────────────┐
│                    Application (App)                     │
│              (Single owner of all Entities)              │
└─────────────────────────────────────────────────────────┘
                            │
        ┌───────────────────┼───────────────────┐
        │                   │                   │
    ┌───────────┐       ┌───────────┐       ┌──────────┐
    │ Entity<A> │       │ Entity<B> │       │ Global<C>│
    └───────────┘       └───────────┘       └──────────┘
        │                   │                   │
        │ read/update       │ read/update       │ via App
        │ via Context<A>    │ via Context<B>    │
        │
    ┌─────────────────────────────────────────────────┐
    │           UI Rendering (Render trait)           │
    │      Each frame: fn render(&mut self, ...)      │
    │      Returns: impl IntoElement (Element tree)   │
    └─────────────────────────────────────────────────┘
        │
        ├─ observe() → changes trigger render
        ├─ subscribe() → events trigger reactions
        ├─ notify() → signal changes
        └─ emit() → send typed events

How to Use

Read individual rule files for detailed explanations and code examples:

rules/core-ownership-model.md
rules/render-render-vs-renderonce.md
rules/anti-silent-error.md

Each rule file contains:

• Brief explanation of why it matters
• Incorrect code example with explanation
• Correct code example with explanation
• Additional context and references