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

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

#[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