gpui-element

Original：🇺🇸 English

Translated

Implementing custom elements using GPUI's low-level Element API (vs. high-level Render/RenderOnce APIs). Use when you need maximum control over layout, prepaint, and paint phases for complex, performance-critical custom UI components that cannot be achieved with Render/RenderOnce traits.

6installs

Sourcelongbridge/gpui-component

Added on2026-02-04

NPX Install

npx skill4agent add longbridge/gpui-component gpui-element

SKILL.md Content

View Translation Comparison →

When to Use

Use the low-level

Element

trait when:

Need fine-grained control over layout calculation
Building complex, performance-critical components
Implementing custom layout algorithms (masonry, circular, etc.)
High-level
```
Render
```
/
```
RenderOnce
```
APIs are insufficient

Prefer
Render
/
RenderOnce
for: Simple components, standard layouts, declarative UI

Quick Start

The

Element

trait provides direct control over three rendering phases:

rust

impl Element for MyElement {
    type RequestLayoutState = MyLayoutState;  // Data passed to later phases
    type PrepaintState = MyPaintState;        // Data for painting

    fn id(&self) -> Option<ElementId> {
        Some(self.id.clone())
    }

    fn source_location(&self) -> Option<&'static std::panic::Location<'static>> {
        None
    }

    // Phase 1: Calculate sizes and positions
    fn request_layout(&mut self, .., window: &mut Window, cx: &mut App)
        -> (LayoutId, Self::RequestLayoutState)
    {
        let layout_id = window.request_layout(
            Style { size: size(px(200.), px(100.)), ..default() },
            vec![],
            cx
        );
        (layout_id, MyLayoutState { /* ... */ })
    }

    // Phase 2: Create hitboxes, prepare for painting
    fn prepaint(&mut self, .., bounds: Bounds<Pixels>, layout: &mut Self::RequestLayoutState,
                window: &mut Window, cx: &mut App) -> Self::PrepaintState
    {
        let hitbox = window.insert_hitbox(bounds, HitboxBehavior::Normal);
        MyPaintState { hitbox }
    }

    // Phase 3: Render and handle interactions
    fn paint(&mut self, .., bounds: Bounds<Pixels>, layout: &mut Self::RequestLayoutState,
             paint_state: &mut Self::PrepaintState, window: &mut Window, cx: &mut App)
    {
        window.paint_quad(paint_quad(bounds, Corners::all(px(4.)), cx.theme().background));

        window.on_mouse_event({
            let hitbox = paint_state.hitbox.clone();
            move |event: &MouseDownEvent, phase, window, cx| {
                if hitbox.is_hovered(window) && phase.bubble() {
                    // Handle interaction
                    cx.stop_propagation();
                }
            }
        });
    }
}

// Enable element to be used as child
impl IntoElement for MyElement {
    type Element = Self;
    fn into_element(self) -> Self::Element { self }
}

Core Concepts

Three-Phase Rendering

request_layout: Calculate sizes and positions, return layout ID and state
prepaint: Create hitboxes, compute final bounds, prepare for painting
paint: Render element, set up interactions (mouse events, cursor styles)

State Flow

RequestLayoutState → PrepaintState → paint

State flows in one direction through associated types, passed as mutable references between phases.

Key Operations

Layout:

window.request_layout(style, children, cx)

- Create layout node

Hitboxes:
```
window.insert_hitbox(bounds, behavior)
```
- Create interaction area
Painting:
```
window.paint_quad(...)
```
- Render visual content
Events:
```
window.on_mouse_event(handler)
```
- Handle user input

Reference Documentation

Complete API Documentation

Element Trait API: See api-reference.md
- Associated types, methods, parameters, return values
- Hitbox system, event handling, cursor styles

Implementation Guides

Examples: See examples.md
- Simple text element with highlighting
- Interactive element with selection
- Complex element with child management
Best Practices: See best-practices.md
- State management, performance optimization
- Interaction handling, layout strategies
- Error handling, testing, common pitfalls
Common Patterns: See patterns.md
- Text rendering, container, interactive, composite, scrollable patterns
- Pattern selection guide
Advanced Patterns: See advanced-patterns.md
- Custom layout algorithms (masonry, circular)
- Element composition with traits
- Async updates, memoization, virtual lists