Gpui Kit

GPUI Kit

Applications depend on one crate, gpui-kit. 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.

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 when the change has a visible surface: code structure preserves product intent, it does not replace it. If the design skill is not installed, fetch https://gpui-kit.com/docs/design-guides.md. The coding guide is a verbatim copy of https://gpui-kit.com/docs/coding-guides.md, so its links to ./design-guides.md and ./getting-started.md mean the design skill and https://gpui-kit.com/docs/getting-started.md.

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 '^## ' references/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 dependency. Applications depend on gpui-kit alone. 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

• Full reference: fetch https://gpui-kit.com/llms-full.txt
• Per-component API: fetch https://gpui-kit.com/docs/components/{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: references/usage.md.

use gpui_kit::*;
use gpui_kit::component::Root;

gpui_kit::application()
    .with_assets(gpui_kit::assets::Assets)
    .run(|cx| {
        gpui_kit::init(cx);                       // first, before anything else
        // ... open_window(..., |window, cx| cx.new(|cx| Root::new(view, 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.

Input & Form

Display & Feedback

Overlay & Popups

Navigation & Layout

Data Display

Chat & Messaging

Charts

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)