gpui-component

Original：🇺🇸 English

Translated

gpui-component library patterns for building reusable UI components. Use when creating buttons, inputs, dialogs, forms, or following Longbridge component library conventions in GPUI applications.

1installs

Sourceaprilnea/gpui-skills

Added on2026-02-15

NPX Install

npx skill4agent add aprilnea/gpui-skills gpui-component

SKILL.md Content

View Translation Comparison →

gpui-component Best Practices

Comprehensive guide for building UI components with gpui-component, a component library for GPUI applications.

When to Apply

Reference these guidelines when:

Creating reusable UI components
Implementing theme-aware styling
Building dialogs, popovers, or sheets
Creating form components (Input, Checkbox, etc.)
Implementing component animations
Following Longbridge component patterns

Rule Categories by Priority


comp-
trait-
theme-
dialog-
form-
anim-

Priority	Category	Impact	Prefix
1	Component Architecture	CRITICAL	`comp-`
2	Trait System	CRITICAL	`trait-`
3	Theme System	HIGH	`theme-`
4	Dialog & Popover	HIGH	`dialog-`
5	Form Components	MEDIUM	`form-`
6	Animation	MEDIUM	`anim-`

Quick Reference

1. Component Architecture (CRITICAL)

```
comp-renderonce
```
- Use RenderOnce with #[derive(IntoElement)]
```
comp-structure
```
- Standard component structure template
```
comp-builder
```
- Fluent builder pattern for components
```
comp-stateful
```
- Entity + RenderOnce for stateful components
```
comp-callbacks
```
- Use Rc<dyn Fn> for event callbacks

2. Trait System (CRITICAL)

```
trait-styled
```
- Implement Styled for style customization
```
trait-disableable
```
- Implement Disableable for disabled state
```
trait-selectable
```
- Implement Selectable for selection state
```
trait-sizable
```
- Implement Sizable with Size enum
```
trait-parent-element
```
- Implement ParentElement for children
```
trait-interactive
```
- Implement InteractiveElement for events

3. Theme System (HIGH)

```
theme-colors
```
- Use ThemeColor for consistent colors
```
theme-active
```
- Use ActiveTheme trait for theme access
```
theme-variants
```
- Implement variant enums (ButtonVariant, etc.)
```
theme-size-system
```
- Use StyleSized for size-based styling

4. Dialog & Popover (HIGH)

```
dialog-root
```
- Use Root component as window root
```
dialog-window-ext
```
- Use WindowExt for dialog management
```
dialog-confirm
```
- Implement confirm/alert dialogs
```
dialog-form
```
- Build form dialogs with input state
```
popover-pattern
```
- Popover vs PopupMenu vs Sheet selection

5. Form Components (MEDIUM)

```
form-input-state
```
- Entity-based input state management
```
form-focus
```
- Focus management with keyed state
```
form-validation
```
- Input validation patterns

6. Animation (MEDIUM)

```
anim-with-animation
```
- Use with_animation for transitions
```
anim-keyed-state
```
- Persist animation state with use_keyed_state
```
anim-easing
```
- Use cubic_bezier for smooth animations

Component Structure Template

rust

#[derive(IntoElement)]
pub struct MyComponent {
    // 1. Identifier
    id: ElementId,

    // 2. Base element (for event delegation)
    base: Div,

    // 3. Style override
    style: StyleRefinement,

    // 4. Content
    label: Option<SharedString>,
    children: Vec<AnyElement>,

    // 5. State configuration
    disabled: bool,
    selected: bool,
    size: Size,

    // 6. Callbacks
    on_click: Option<Rc<dyn Fn(&ClickEvent, &mut Window, &mut App)>>,
}

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│  Window                                                      │
│  ├── Root (Entity, manages overlay state)                   │
│  │   ├── view: AnyView (user's main view)                   │
│  │   ├── active_dialogs: Vec<ActiveDialog>                  │
│  │   ├── active_sheet: Option<ActiveSheet>                  │
│  │   └── notification: Entity<NotificationList>             │
│  │                                                          │
│  └── Render Layers                                          │
│      ├── Layer 0: Root.view (main content)                  │
│      ├── Layer 1: Sheet (side drawer)                       │
│      ├── Layer 2: Dialogs (stackable)                       │
│      └── Layer 3: Notifications                             │
└─────────────────────────────────────────────────────────────┘

Popup Component Comparison

Feature	Dialog	Popover	PopupMenu	Sheet
Position	Centered	Anchored	Anchored	Side
Overlay	Yes	No	No	Yes
State	Root	keyed_state	Entity	Root
Stacking	Multiple	Single	Submenus	Single
Close	ESC/Click/Button	ESC/Outside	ESC/Select	ESC/Overlay

How to Use

Read individual rule files for detailed explanations and code examples:

rules/comp-renderonce.md
rules/trait-styled.md
rules/dialog-root.md

Each rule file contains:

Brief explanation of why it matters
Code examples with correct patterns
Common mistakes to avoid