How do I install the Gpui Fundamentals skill?

Run npx skillmds@latest add tomevault-io/gpui-fundamentals in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

What does the Gpui Fundamentals skill do?

Core GPUI concepts including contexts, windows, entities, elements, and rendering. Use when learning GPUI basics, understanding the framework architecture, or implementing core UI patterns. Use when this capability is needed. It is listed under Coding & Dev Tools on SkillMD.

Is Gpui Fundamentals safe to use?

This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: PASS, Skill Scanner: PASS. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Gpui Fundamentals?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Gpui Fundamentals free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Gpui Fundamentals?

tomevault-io (@tomevault-io) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Gpui Fundamentals by tomevault-io — Agent Skill

Name: Gpui Fundamentals
Author: tomevault-io

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

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

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
});

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

```rust
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


---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/zerx-lab) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-11 -->

Gpui Fundamentals

File contents

GPUI Fundamentals

Overview

Context Types

App

Context

AsyncApp and AsyncWindowContext

Window

Entities

Creating Entities

Entity Operations

Important Rules

Elements

Render Trait

RenderOnce Trait

SharedString

Element Composition

Basic Composition

Conditional Rendering

Multiple Children

Application Lifecycle

Basic Application

Window Options

Common Patterns

State Update with Notify

Event Handlers

Using cx.listener

Performance Tips

1. Minimize Entity Updates

2. Use WeakEntity for Callbacks

3. Batch Notifications

4. Avoid Unnecessary Clones

Common Mistakes

Summary

References

Frequently asked questions

Gpui Fundamentals

File contents

GPUI Fundamentals

Overview

Context Types

App

Context

AsyncApp and AsyncWindowContext

Window

Entities

Creating Entities

Entity Operations

Important Rules

Elements

Render Trait

RenderOnce Trait

SharedString

Element Composition

Basic Composition

Conditional Rendering

Multiple Children

Application Lifecycle

Basic Application

Window Options

Common Patterns

State Update with Notify

Event Handlers

Using cx.listener

Performance Tips

1. Minimize Entity Updates

2. Use WeakEntity for Callbacks

3. Batch Notifications

4. Avoid Unnecessary Clones

Common Mistakes

Summary

References

Related skills

Frequently asked questions

How do I install the Gpui Fundamentals skill?

What does the Gpui Fundamentals skill do?

Is Gpui Fundamentals safe to use?

Which AI agents work with Gpui Fundamentals?

Is Gpui Fundamentals free to use?

Who published Gpui Fundamentals?