gpui-component/docs/docs/getting-started.md

title	description	order
Getting Started	Learn how to set up and use GPUI Component in your project	-2

Getting Started

GPUI Component is a comprehensive UI component library for building fantastic desktop applications using GPUI. It provides 40+ cross-platform components with modern design, theming support, and high performance.

Features

• Richness: 40+ cross-platform desktop UI components
• Native: Inspired by macOS and Windows controls, combined with shadcn/ui design
• Ease of Use: Stateless RenderOnce components, simple and user-friendly
• Customizable: Built-in Theme and ThemeColor, supporting multi-theme
• Versatile: Supports sizes like xs, sm, md, and lg
• Flexible Layout: Dock layout for panel arrangements, resizing, and freeform (Tiles) layouts
• High Performance: Virtualized Table and List components for smooth large-data rendering
• Content Rendering: Native support for Markdown and simple HTML
• Charting: Built-in charts for visualization
• Editor: High performance code editor with LSP support
• Syntax Highlighting: Using Tree Sitter

Installation

Add dependencies to your Cargo.toml:

[dependencies]
gpui = "0.2.0"
gpui-component = "0.2.0"

Quick Start

Here's a simple example to get you started:

use gpui::*;
use gpui_component::{button::*, *};

pub struct HelloWorld;

impl Render for HelloWorld {
    fn render(&mut self, _: &mut Window, _: &mut Context<Self>) -> impl IntoElement {
        div()
            .v_flex()
            .gap_2()
            .size_full()
            .items_center()
            .justify_center()
            .child("Hello, World!")
            .child(
                Button::new("ok")
                    .primary()
                    .label("Let's Go!")
                    .on_click(|_, _, _| println!("Clicked!")),
            )
    }
}

fn main() {
    let app = Application::new();

    app.run(move |cx| {
        // This must be called before using any GPUI Component features.
        gpui_component::init(cx);

        cx.spawn(async move |cx| {
            cx.open_window(WindowOptions::default(), |window, cx| {
                let view = cx.new(|_| HelloWorld);
                // This first level on the window, should be a Root.
                cx.new(|cx| Root::new(view.into(), window, cx))
            })?;

            Ok::<_, anyhow::Error>(())
        })
        .detach();
    });
}

Basic Concepts

Stateless Components

GPUI Component uses stateless RenderOnce components, making them simple and predictable. State management is handled at the view level, not in individual components.

Theming

All components support theming through the built-in Theme system:

use gpui_component::{ActiveTheme, Theme};

// Access theme colors in your components
cx.theme().primary
cx.theme().background
cx.theme().foreground

Sizing

Most components support multiple sizes:

Button::new("btn").small()
Button::new("btn").medium() // default
Button::new("btn").large()
Button::new("btn").xsmall()

Variants

Components offer different visual variants:

Button::new("btn").primary()
Button::new("btn").danger()
Button::new("btn").warning()
Button::new("btn").success()
Button::new("btn").ghost()
Button::new("btn").outline()

Icons

GPUI Component has an Icon element, but does not include SVG files by default.

The examples use Lucide icons. You can use any icons you like by naming the SVG files as defined in IconName. Add the icons you need to your project.

use gpui_component::{Icon, IconName};

Icon::new(IconName::Check)
Icon::new(IconName::Search).small()

Next Steps

Explore the component documentation to learn more about each component:

• Button - Interactive button component
• Input - Text input with validation
• Modal - Dialog and modal windows
• Table - High-performance data tables
• More components...

Development

To run the component gallery:

cargo run

More examples can be found in the examples directory:

cargo run --example <example_name>