Getting Started

Native controls with reusable behavior and replaceable presentation.

Build with published crates

Luma 2.0.0 uses gpui-unofficial 1.27.0. This is a breaking backend change; applications must use the same gpui-unofficial version. Keep the dependency aliases gpui and gpui_platform shown below so existing Rust imports continue to work. Browser builds use gpui-web-gpui-unofficial, aliased as gpui_web.

Use the libraries from crates.io in your own Rust application. No GitHub checkout is required. Start with cargo new luma-hello, then use the dependencies and src/main.rs in the complete app below. Run cargo build to build it or cargo run to launch it.

Support includes the SDK’s built-in light/dark styling, Shadcn, and Radix. Add gpui-luma-color = "2.0" for color controls or gpui-luma-plot = "2.0" for charts. Use a recent stable Rust toolchain and your platform’s native GPUI build prerequisites.

Use 2.0 for Luma dependencies to accept compatible 2.x releases. Run cargo update to refresh versions already recorded in Cargo.lock.

Run the sample apps

Luma Studio with the Polaris theme editor and control gallery menu open.

Explore the runnable apps alongside these docs. The repository includes workbenches for both Looks, a native chart gallery, and sample application shells. Their source shows how controls, themes, layouts, and events fit together in a complete application.

Use release builds for optimal app performance. Debug builds are intended for development and can make rendering and interactions noticeably slower. The app recipes below use release builds by default.

Clone the repository to run its sample apps. From the repository root, use the following justfile recipes. They launch native desktop applications in release mode by default; use just --set profile dev <recipe> for development builds. Run just to list recipes without launching an app. Without just, use cargo run -p <package> --release.

Sample / sourceWhat to exploreRun
Luma StudioShadcn control examples and theme inspection. See Look-shadcn.just app-studio
Radix StudioRadix style guide, palette editor, and control previews. See Look-radix.just app-radix
Plot VizNative SDK application with line, area, bar, pie/donut, radar, and radial chart galleries. Monochrome SDK controls support live light/dark switching; chart colors use independent palettes. See Plots.just app-plot
Detached shellA sample application shell with detached-style regions.just shell-detached
Split-titlebar shellA sample shell with a split titlebar layout.just shell-split-titlebar
VS Code shellA workbench-style shell with configurable workspace regions.just shell-vscode
Shell 2026An alternative application shell and titlebar composition.just shell-2026

Shell themes: the shell recipes use the default theme when no argument is given. To choose a built-in Shadcn theme, pass it directly, for example just shell-vscode retro-arcade. Radix Studio uses Radix palettes; Plot Viz uses the SDK baseline. Neither accepts Shadcn named CSS themes.

Development: use just --set profile dev app-studio, just --set profile dev app-radix, or just --set profile dev app-plot. just --set profile dev app-studio-backtrace enables Rust backtraces in debug mode; just perf-studio enables the Metal HUD in release mode.

Library checks: just sdk-check, just sdk-build, just sdk-test, just sdk-clippy, and just sdk-doc-test provide SDK/library checks. Check, build, and Clippy target the five default library crates; test recipes use CI’s selected library suites, including luma-app-common in sdk-test. Use just workspace-check, just workspace-build, or just workspace-test for the full workspace. just apps-build compiles all native apps without launching them. just ci runs formatting checks, Python helper tests, workspace Clippy, selected library tests and doc-tests, and control documentation checks. Use just fmt to format the workspace.

Before a PR: run just pre-pr. It runs formatting, workflow lint, native and WASM Clippy, library tests and doc-tests, documentation example compilation, Python helper/packaging tests, JavaScript syntax checks, and whitespace checks. Sample app tests and deployment builds are excluded. Install Node.js and actionlint on your PATH and add the wasm32-unknown-unknown Rust target first.

What you get

Controls, layouts, focus and input handling, semantic events, and customizable templates. Shadcn and Radix Look crates provide ready-to-use styling.

Philosophy & design

The SDK owns behavior. Templates own presentation. Looks configure a visual system. Customize content, modify a template, or replace it without rebuilding the control’s interaction logic.

Templating examples →

A small complete app

A single window with a native Shadcn button. In the new app’s Cargo.toml, use these published dependencies:

Cargo.toml · crates.io
[package]
name = "luma-hello"
version = "0.1.0"
edition = "2024"

[dependencies]
gpui = { package = "gpui-unofficial", version = "=1.27.0" }
gpui_platform = { package = "gpui-platform-gpui-unofficial", version = "=1.27.0", features = ["font-kit"] }
gpui-luma = "2.0"
gpui-luma-look-shadcn = "2.0"
src/main.rs
use gpui::{prelude::*, Context, Entity, Render, Window, WindowOptions, div};
use gpui_luma::controls::button::Button;
use gpui_luma::infra::presenter::HasPresenter;
use gpui_luma_look_shadcn as shadcn;

struct Hello {
    button: Entity<Button>,
    saves: usize,
}

impl Hello {
    fn new(cx: &mut Context<Self>) -> Self {
        let button = shadcn::Button::new("hello")
            .primary().label("Hello, Luma")
            .on_click(cx, |app, cx| {
                app.saves += 1;
                cx.notify();
            })
            .spawn(cx);
        Self { button, saves: 0 }
    }
}

impl Render for Hello {
    fn render(&mut self, _: &mut Window, _: &mut Context<Self>)
        -> impl IntoElement
    {
        div().size_full().flex().flex_col().gap_2().items_center().justify_center()
            .child(self.button.clone())
            .child(format!("Saved {} times", self.saves))
    }
}

fn main() {
    gpui_platform::application().run(|cx| {
        if let Err(error) = gpui_luma::init(cx) {
            eprintln!("Initialization failed: {error}");
            return;
        }
        gpui_luma::focus::bind_default_focus_keys(cx);
        gpui_luma::key_handling::bind_default_control_keys(cx);
        if let Err(error) = cx.open_window(WindowOptions::default(), |_, cx| {
            cx.new(Hello::new)
        }) {
            eprintln!("Window creation failed: {error}");
            return;
        }
        cx.activate(true);
    });
}

This standalone app uses published crates and does not need the Luma workspace. Build with cargo build; launch with cargo run.