version: "1.0.0" name: gpui-fundamentals description: Core GPUI concepts including contexts, windows, entities, elements, and rendering. Use when learning GPUI basics, understanding the framework architecture, or implementing core UI patterns.

GPUI Fundamentals

This skill covers the core concepts of GPUI framework for building desktop UI applications in Rust.

Overview

GPUI is a UI framework that provides:

• Entities: Handles to state with lifecycle management
• Contexts: Access to global state, windows, and system services
• Elements: Composable UI building blocks
• Rendering: Render trait for creating element trees
• Concurrency: Async primitives for background work

Context Types

Context types allow interaction with global state, windows, entities, and system services. They are passed as the argument named cx.

App

App is the root context type, providing access to global state and read/update of entities.

fn do_something(cx: &mut App) {
    // Access global state
    // Read/update entities
}

Context<T>

Provided when updating an Entity<T>. This context dereferences into App, so functions which take &App can also take &Context<T>.

struct MyView {
    count: usize,
}
 
impl MyView {
    fn increment(&mut self, cx: &mut Context<Self>) {
        self.count += 1;
        cx.notify(); // Tell GPUI to re-render
    }
}

AsyncApp and AsyncWindowContext

Provided by cx.spawn() for async operations. These can be held across await points.

fn start_async_work(&mut self, cx: &mut Context<Self>) {
    cx.spawn(async move |this, cx| {
        // this: WeakEntity<Self>
        // cx: &mut AsyncApp
        
        // Do async work
        Ok(())
    }).detach();
}

Window

Window provides access to the state of an application window. It is passed as an argument named window and comes before cx when present.

impl Render for MyView {
    fn render(&mut self, window: &mut Window, cx: &mut Context<Self>) -> impl IntoElement {
        div().child("Hello")
    }
}

Used for:

• Managing focus
• Dispatching actions
• Directly drawing
• Getting user input state

Entities

An Entity<T> is a handle to state of type T. Entities enable:

• Shared ownership of UI state
• Automatic lifecycle management
• Safe concurrent access

Creating Entities

app.run(move |cx| {
    cx.spawn(async move |cx| {
        cx.open_window(WindowOptions::default(), |window, cx| {
            // Create an entity
            cx.new(|_cx| MyView { count: 0 })
        })?;
        
        Ok::<_, anyhow::Error>(())
    }).detach();
});

Entity Operations

// Given: thing: Entity<MyView>
 
// Get entity ID
let id = thing.entity_id();
 
// Downgrade to weak reference
let weak = thing.downgrade();
 
// Read (immutable access)
let value = thing.read(cx);
println!("Count: {}", value.count);
 
// Read with closure
let count = thing.read_with(cx, |view, cx| view.count);
 
// Update (mutable access)
thing.update(cx, |view, cx| {
    view.count += 1;
    cx.notify();
});
 
// Update with window access
thing.update_in(cx, |view, window, cx| {
    view.count += 1;
    window.dispatch_action(SomeAction.boxed_clone(), cx);
    cx.notify();
});

Important Rules

1. Use inner cx: Within closures, use the inner cx provided to the closure, not the outer cx

// ❌ WRONG
entity.update(cx, |view, inner_cx| {
    view.count += 1;
    cx.notify(); // Using outer cx - WRONG!
});
 
// ✅ CORRECT
entity.update(cx, |view, inner_cx| {
    view.count += 1;
    inner_cx.notify(); // Using inner cx
});

1. Avoid update-while-updating: Never update an entity while it's already being updated (causes panic)

// ❌ WRONG - will panic
entity.update(cx, |view, cx| {
    entity.update(cx, |view2, cx2| { // Nested update - PANIC!
        // ...
    });
});

Elements

The Render trait is used to render state into an element tree with flexbox layout.

Render Trait

use gpui::*;
 
struct MyView {
    text: SharedString,
}
 
impl Render for MyView {
    fn render(&mut self, _window: &mut Window, _cx: &mut Context<Self>) -> impl IntoElement {
        div()
            .flex()
            .flex_col()
            .gap_2()
            .child(self.text.clone())
            .child("More text")
    }
}

RenderOnce Trait

For components constructed just to be turned into elements:

use gpui::*;
 
#[derive(IntoElement)]
struct Card {
    title: SharedString,
    content: SharedString,
}
 
impl RenderOnce for Card {
    fn render(self, _window: &mut Window, _cx: &mut App) -> impl IntoElement {
        div()
            .p_4()
            .bg(rgb(0x1a1a1a))
            .rounded(px(8.0))
            .child(
                div().font_bold().child(self.title)
            )
            .child(
                div().text_sm().child(self.content)
            )
    }
}
 
// Usage
impl Render for MyView {
    fn render(&mut self, _window: &mut Window, _cx: &mut Context<Self>) -> impl IntoElement {
        div().child(Card {
            title: "Hello".into(),
            content: "World".into(),
        })
    }
}

SharedString

Use SharedString to avoid copying strings. It's either &'static str or Arc<str>.

use gpui::*;
 
struct MyView {
    // Efficient string storage
    title: SharedString,
}
 
impl MyView {
    fn new() -> Self {
        Self {
            title: "Hello".into(), // From &str
        }
    }
    
    fn set_title(&mut self, title: String) {
        self.title = title.into(); // From String
    }
}
 
// SharedString implements IntoElement
impl Render for MyView {
    fn render(&mut self, _window: &mut Window, _cx: &mut Context<Self>) -> impl IntoElement {
        div().child(self.title.clone())
    }
}

Element Composition

Basic Composition

div()
    .child("Text")
    .child(div().child("Nested"))
    .child(another_element())

Conditional Rendering

Use .when() for conditional attributes/children:

div()
    .when(is_active, |this| {
        this.bg(rgb(0x3b82f6))
    })
    .when_some(maybe_text, |this, text| {
        this.child(text)
    })

Multiple Children

div()
    .children(vec![
        div().child("Item 1"),
        div().child("Item 2"),
        div().child("Item 3"),
    ])

Application Lifecycle

Basic Application

use gpui::*;
 
struct AppView;
 
impl Render for AppView {
    fn render(&mut self, _window: &mut Window, _cx: &mut Context<Self>) -> impl IntoElement {
        div().size_full().child("My App")
    }
}
 
fn main() {
    let app = Application::new();
    
    app.run(move |cx| {
        cx.spawn(async move |cx| {
            cx.open_window(WindowOptions::default(), |window, cx| {
                cx.new(|_| AppView)
            })?;
            
            Ok::<_, anyhow::Error>(())
        })
        .detach();
    });
}

Window Options

use gpui::*;
 
let options = WindowOptions {
    window_bounds: Some(WindowBounds::Windowed(Bounds {
        origin: Point { x: px(100.0), y: px(100.0) },
        size: Size { width: px(1024.0), height: px(768.0) },
    })),
    titlebar: Some(TitlebarOptions {
        title: Some("My Application".into()),
        appears_transparent: false,
        ..Default::default()
    }),
    focus: true,
    show: true,
    ..Default::default()
};
 
cx.open_window(options, |window, cx| {
    cx.new(|_| MyView::new())
})?;

Common Patterns

State Update with Notify

When state changes in a way that affects rendering:

struct Counter {
    count: usize,
}
 
impl Counter {
    fn increment(&mut self, cx: &mut Context<Self>) {
        self.count += 1;
        cx.notify(); // Trigger re-render
    }
}

Event Handlers

impl Render for Counter {
    fn render(&mut self, _window: &mut Window, cx: &mut Context<Self>) -> impl IntoElement {
        div()
            .child(format!("Count: {}", self.count))
            .child(
                div()
                    .child("Increment")
                    .on_click(cx.listener(|this, _event, _window, cx| {
                        this.increment(cx);
                    }))
            )
    }
}

Using cx.listener

The cx.listener() method creates event handlers that receive &mut Self:

.on_click(cx.listener(|this: &mut Self, event, window, cx| {
    // this: mutable reference to the entity
    // event: the click event
    // window: window reference
### Todo List with Entity Management
 

use gpui::*;

#[derive(Clone)] struct TodoItem { id: usize, text: String, completed: bool, }

struct TodoList { items: Vec<TodoItem>, next_id: usize, input_text: SharedString, }

impl TodoList { fn new() -> Self { Self { items: Vec::new(), next_id: 1, input_text: "".into(), } }

fn add_item(&mut self, cx: &mut Context<Self>) { if !self.input_text.is_empty() { self.items.push(TodoItem { id: self.next_id, text: self.input_text.to_string(), completed: false, }); self.next_id += 1; self.input_text = "".into(); cx.notify(); } }

fn toggle_item(&mut self, id: usize, cx: &mut Context<Self>) { if let Some(item) = self.items.iter_mut().find(|i| i.id == id) { item.completed = !item.completed; cx.notify(); } }

fn remove_item(&mut self, id: usize, cx: &mut Context<Self>) { self.items.retain(|item| item.id != id); cx.notify(); } }

impl Render for TodoList { fn render(&mut self, _window: &mut Window, cx: &mut Context<Self>) -> impl IntoElement { div() .size_full() .p_6() .bg(rgb(0x0f0f0f)) .flex() .flex_col() .gap_4() .child( div() .text_2xl() .font_bold() .text_color(rgb(0xffffff)) .child("Todo List") ) .child( div() .flex() .gap_2() .child( div() .flex_1() .px_3() .py_2() .bg(rgb(0x1a1a1a)) .border_1() .border_color(rgb(0x4a4a4a)) .rounded_md() .child(self.input_text.clone()) ) .child( div() .px_4() .py_2() .bg(rgb(0x3b82f6)) .rounded_md() .cursor_pointer() .child("Add") .on_click(cx.listener(|this, _event, _window, cx| { this.add_item(cx); })) ) ) .child( div() .flex() .flex_col() .gap_2() .children( self.items.iter().map(|item| { let id = item.id; div() .flex() .items_center() .gap_2() .p_3() .bg(rgb(0x1a1a1a)) .rounded_md() .child( div() .w(px(20.0)) .h(px(20.0)) .border_2() .border_color(rgb(0x3b82f6)) .rounded(px(4.0)) .cursor_pointer() .when(item.completed, |this| { this.bg(rgb(0x3b82f6)) }) .on_click(cx.listener(move |this, _event, _window, cx| { this.toggle_item(id, cx); })) ) .child( div() .flex_1() .text_color(if item.completed { rgb(0x6b7280) } else { rgb(0xffffff) }) .when(item.completed, |this| { this.line_through() }) .child(&item.text) ) .child( div() .px_3() .py_1() .bg(rgb(0xef4444)) .rounded(px(4.0)) .cursor_pointer() .child("×") .on_click(cx.listener(move |this, _event, _window, cx| { this.remove_item(id, cx); })) ) }) ) ) } }

 
## Performance Tips
 
### 1. Minimize Entity Updates
 

// ❌ BAD - Multiple updates entity.update(cx, |view, cx| { view.x = 10; cx.notify(); }); entity.update(cx, |view, cx| { view.y = 20; cx.notify(); }); entity.update(cx, |view, cx| { view.z = 30; cx.notify(); });

// ✅ GOOD - Single update entity.update(cx, |view, cx| { view.x = 10; view.y = 20; view.z = 30; cx.notify(); });

 
### 2. Use WeakEntity for Callbacks
 

// ❌ BAD - Strong reference can leak struct Parent { child: Entity<Child>, }

// ✅ GOOD - Weak reference prevents leaks struct Callback { target: WeakEntity<Target>, }

 
### 3. Batch Notifications
 

struct BatchUpdate { needs_notify: bool, }

impl BatchUpdate { fn update_multiple(&mut self, cx: &mut Context<Self>) { self.field1 = value1; self.field2 = value2; self.field3 = value3;

// Single notify at the end cx.notify(); } }

 
### 4. Avoid Unnecessary Clones
 

// ❌ BAD - Unnecessary clone div().child(self.text.clone().to_string())

// ✅ GOOD - Use SharedString directly div().child(self.text.clone())

 
## Common Mistakes
 
| Mistake | Fix |
|---------|-----|
| Using outer `cx` in update closure | Use the inner `cx` provided to closure |
| Nested entity updates | Restructure to avoid updating entity while updating |
| Forgetting `cx.notify()` | Call after state changes that affect rendering |
| Not using `SharedString` | Use `SharedString` for text to avoid copies |
| Update without window in `Render` | Use Context methods that don't need Window |
| Calling `.unwrap()` on entity operations | Use `?` or handle errors properly |
| Not storing `Subscription` | Store in struct field to keep subscription alive |
| Using `smol::Timer` in tests | Use `cx.background_executor.timer()` |
 
## Summary
 
- **Entities** (`Entity<T>`): Handles to shared state
- **Contexts** (`App`, `Context<T>`): Access to framework services
- **Window**: Window-specific operations
- **Elements**: Built with `div()` and styled with methods
- **Render**: Trait for converting state to UI
- **SharedString**: Efficient string type for UI text
 
## References
 
- [GPUI Documentation](https://gpui.rs)
- [Zed GEMINI.md](https://github.com/zed-industries/zed/blob/main/GEMINI.md)