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

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

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