GPUI组件开发指南：创建无状态、有状态和组合组件的完整教程

🇺🇸English

Instructions

When creating new GPUI components:

1. Follow existing patterns : Base implementation on components in crates/ui/src (examples: Button, Select, Dialog)
2. Style consistency : Follow existing component styles and Shadcn UI patterns
3. Component type decision :
   • Use stateless elements for simple components (like Button)
   • Use stateful elements for complex components with data (like Select and SelectState)
   • Use composition for components built on existing components (like AlertDialog based on Dialog)
4. API consistency : Maintain the same API style as other elements
5. Documentation : Create component documentation
6. Stories : Write component stories in the story folder
7. Registration : Add the component to crates/story/src/main.rs story list

Component Types

• Stateless : Pure presentation components without internal state (e.g., Button)
• Stateful : Components that manage their own state and data (e.g., Select)
• Composite : Components built on top of existing components (e.g., AlertDialog based on Dialog)

Implementation Steps

1. Create Component File

Create a new file in crates/ui/src/ (e.g., alert_dialog.rs):

use gpui::{App, ClickEvent, Pixels, SharedString, Window, px};
use std::rc::Rc;

pub struct AlertDialog {
    pub(crate) variant: AlertVariant,
    pub(crate) title: SharedString,
    // ... other fields
}

impl AlertDialog {
    pub fn new(title: impl Into<SharedString>) -> Self {
        // implementation
    }

    // Builder methods
    pub fn description(mut self, desc: impl Into<SharedString>) -> Self {
        // implementation
    }
}

2. Register in lib.rs

Add the module to crates/ui/src/lib.rs:

pub mod alert_dialog;

3. Extend WindowExt (if needed)

For dialog-like components, add helper methods to window_ext.rs:

pub trait WindowExt {
    fn open_alert_dialog(&mut self, alert: AlertDialog, cx: &mut App);
}

4. Create Story

Create crates/story/src/stories/alert_dialog_story.rs:

pub struct AlertDialogStory {
    focus_handle: FocusHandle,
}

impl Story for AlertDialogStory {
    fn title() -> &'static str {
        "AlertDialog"
    }

    fn new_view(window: &mut Window, cx: &mut App) -> Entity<impl Render> {
        Self::view(window, cx)
    }
}

5. Register Story

Add to crates/story/src/stories/mod.rs:

mod alert_dialog_story;
pub use alert_dialog_story::AlertDialogStory;

Add to crates/story/src/main.rs in the stories list:

vec![
    StoryContainer::panel::<AlertStory>(window, cx),
    StoryContainer::panel::<AlertDialogStory>(window, cx),  // Add here
    // ...
]

Real Example: AlertDialog

AlertDialog is a composite component based on Dialog with these features:

1. Simpler API : Pre-configured for common alert scenarios
2. Center-aligned layout : All content (icon, title, description, buttons) is center-aligned
3. Vertical layout : Icon appears at the top, followed by title and description
4. Auto icons : Automatically shows icons based on variant (Info, Success, Warning, Error)
5. Convenience constructors : AlertDialog::info(), AlertDialog::warning(), etc.

Key Design Decisions :

• description uses SharedString instead of AnyElement because the Dialog builder needs to be Fn (callable multiple times), and AnyElement cannot be cloned
• Implementation is in window_ext.rs using Dialog as the base, not as a separate IntoElement component
• Center-aligned layout : Icon is positioned at the top (not left), all text is center-aligned for a more focused alert appearance
• Footer center-aligned : Buttons are centered, different from Dialog's default right-aligned footer

Usage :

window.open_alert_dialog(
    AlertDialog::warning("Unsaved Changes")
        .description("You have unsaved changes.")
        .show_cancel(true)
        .on_confirm(|_, window, cx| {
            window.push_notification("Confirmed", cx);
            true
        }),
    cx,
);

Common Patterns

Builder Pattern

All components use the builder pattern for configuration:

AlertDialog::new("Title")
    .description("Description")
    .width(px(500.))
    .on_confirm(|_, _, _| true)

Size Variants

Implement Sizable trait for components that support size variants (xs, sm, md, lg).

Variants

Use enums for visual variants (e.g., AlertVariant::Info, ButtonVariant::Primary).

Styled Trait Implementation

Components that render as a single container element should implement Styled to allow callers to customize styles. The pattern uses a StyleRefinement field and refine_style() from StyledExt:

use gpui::{AnyElement, App, IntoElement, ParentElement, RenderOnce, StyleRefinement, Styled, Window, div};
use crate::StyledExt as _;

#[derive(IntoElement)]
pub struct MyComponent {
    style: StyleRefinement,
    children: Vec<AnyElement>,
}

impl MyComponent {
    pub fn new() -> Self {
        Self {
            style: StyleRefinement::default(),
            children: Vec::new(),
        }
    }
}

impl ParentElement for MyComponent {
    fn extend(&mut self, elements: impl IntoIterator<Item = AnyElement>) {
        self.children.extend(elements);
    }
}

impl Styled for MyComponent {
    fn style(&mut self) -> &mut StyleRefinement {
        &mut self.style
    }
}

impl RenderOnce for MyComponent {
    fn render(self, _: &mut Window, _: &mut App) -> impl IntoElement {
        div()
            // ... component's default styles ...
            .refine_style(&self.style)  // Apply user's style overrides
            .children(self.children)
    }
}

Key points:

• Add style: StyleRefinement field initialized with StyleRefinement::default()
• Implement Styled trait returning &mut self.style
• In render(), call .refine_style(&self.style) on the root div to merge user styles
• Place .refine_style() after component defaults but before .children() so user styles override defaults
• Reference: crates/ui/src/dialog/header.rs (DialogHeader), crates/ui/src/table/table.rs (Table and sub-components)

Callbacks

Use Rc<dyn Fn> for callbacks that may be called multiple times:

on_confirm: Option<Rc<dyn Fn(&ClickEvent, &mut Window, &mut App) -> bool + 'static>>

Weekly Installs

120

Repository

longbridge/gpui…omponent

GitHub Stars

10.7K

First Seen

Jan 21, 2026

Security Audits

Gen Agent Trust HubPassSocketPassSnykPass

Installed on

opencode110

codex106

gemini-cli104

cursor99

github-copilot98

claude-code96