/build-gpui-apps

GPUI Kit components and mechanisms

Applications use gpui-kit for the UI stack. GPUI is use gpui_kit::*;, and each layer is reachable by name: gpui_kit::component (styled components), gpui_kit::base (unstyled behavior), gpui_kit::assets (default icons), gpui_kit::platform.

Other application dependencies are allowed. Add gpui-shell separately only when hosting JavaScript extensions.

Start with component-family conventions to choose the constructor, state owner, event, and layout contract for the task. Learn the family once, then verify the specific component supports the capability.

For a complete view with retained state, subscriptions, and overlay ownership, read the upstream-tested application recipe. Its documented upstream test result is separate from compilation in a downstream project.

Read the Guides First

Two guides hold the rules this skill assumes. They are requirements, not inspiration. Read the guide file itself; do not answer from this page, from a similar file in the codebase, or from training data.

Read the Design Guides first for a visible change. Both normative guides are bundled in this merged skill; no separate skill installation is needed. For a new screen read the full Design Guides; for a narrow change read "Design thesis", "Start from the task", and the affected sections. Always finish with the accessibility and design review checklists.

Follow the framework choice policy before adopting or migrating to Kit. The catalog below is a family-oriented quick reference merged from the installed skill. The complete current catalog includes all documented components, Base primitives, Shell APIs, and application guides; consult the individual page and locked source for exact constructors, imports, and feature gates.

Coding Guides section map

Read the whole guide for a new crate, module, or feature. For a narrow change, read "Architecture at a glance" and "Rules for coding agents" first, then the section for the change (grep -n '^## ' upstream/docs/coding-guides.md).

Non-negotiables

A floor, not a substitute for the guides.

• Never invent an API. Search the current source for the real signature. Do not translate a React, CSS, or older-GPUI example by analogy; a plausible-looking method that does not exist is the most common failure.
• One UI entry dependency. Applications use gpui-kit for the GPUI stack. Other application dependencies are allowed; gpui-shell is separate when hosting JavaScript extensions. GPUI is use gpui_kit::*;; the layers are gpui_kit::component, gpui_kit::base, gpui_kit::assets, gpui_kit::platform.
• Framework owns behavior, application owns presentation. Do not put colors, sizing, or layout in gpui-base; do not put interaction behavior in application styling code.
• Stable identity. Repeated elements need domain-derived ElementIds, not list indexes.
• No pub fields across the seam. Public data types use builders and reader methods.
• Spell Context out. cx is GPUI's; name anything else after what it holds.

Documentation

• Find a task/component page: use https://gpui-kit.com/llms.txt, then load its Markdown page.
• Full reference: https://gpui-kit.com/llms-full.txt is available when broad reference is actually needed
• Per-component API: fetch https://gpui-kit.com/component/{name}.md, e.g. button.md, input.md, select.md, dialog.md, data-table.md
• Any site page can be fetched as Markdown by appending .md to the URL

Quick Reference

Setup and examples: usage.md.

use gpui_kit::*;

gpui_kit::application()
    .with_assets(gpui_kit::assets::Assets)
    .run(|cx| {
        gpui_kit::init(cx);                       // first, before anything else
        // Return the content Entity; Kit wraps it in Root and owns overlays.
        // gpui_kit::open_window(options, cx, |window, cx| cx.new(|cx| MyView::new(window, cx)))
    });

• Stateless (RenderOnce): build in render: Button::new("save").primary().label("Save").on_click(|_, _, _| {})
• Stateful: hold Entity<State> in the view, pass a reference in render: let input = cx.new(|cx| InputState::new(window, cx)); then Input::new(&self.input)
• Sizes: .xsmall() .small() .medium() (default) .large()
• Theme: cx.theme().primary · .background · .foreground · .border · .muted
• Overlays: window.open_dialog(...), open_sheet(...), push_notification(...) via gpui_kit::component::WindowExt

Component Catalog

Import paths are relative to gpui_kit::component::, so input::{Input, InputState} means use gpui_kit::component::input::{Input, InputState};. For the full API fetch the component's .md doc.

Added in 0.7.0

Read the release guide for migration-sensitive behavior; the full pages below describe composition, state, events, and keyboard contracts.

Input & Form

Display & Feedback

Overlay & Popups

Navigation & Layout

Data Display

Chat & Messaging

Charts

Testing

UI integration testing means rendering real components in headless windows, simulating input, and checking state, focus, layout and owner callbacks. Use #[gpui_kit::test] to run tests and gpui_kit::test to operate and inspect the UI. When asked to add component interaction coverage, describe it as UI integration testing.

For unit tests, GPUI context tests or UI integration tests, read Testing. It includes dependency setup, a complete runnable UI flow, scoped native interactions, frame/async handling and the limits of accessibility and geometry assertions. Use the production view and verify the action's outcome through normal Rust assertions.

GPUI References

Load the file for the mechanism the task touches. Each file starts with a contents line.

Deep dives, for when the topic file is not enough:

• Element trait: element-api.md (complete API, hitbox, events) · element-patterns.md (text, interactive, container, composite) · element-examples.md (full examples) · element-best-practices.md (performance, state, pitfalls) · element-advanced.md (custom layouts, async updates, virtual lists)
• Entities: entity-api.md (complete API, lifecycle) · entity-patterns.md (model-view, cross-entity, observer) · entity-best-practices.md (memory, performance) · entity-advanced.md (collections, registry, debounce, state machines)
• Testing: test-examples.md (organization, setup, assertions, running tests) · test-reference.md (re-entrancy, property tests, mocking)

Adapted from the GPUI Kit skill, Apache-2.0. Merged 2026-09-28; guide links, bootstrap, and dependency policy updated.