Imported from longbridge/gpui-kit (skills/gpui-kit/SKILL.md). Install upstream with npx skills add longbridge/gpui-kit --skill gpui-kit. Copyright stays with the author.

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.

Guide	Read before
Design Guides, skill `gpui-kit-design-guides`	Choosing components, layout, spacing, hierarchy, color, density, interaction states, overlays, motion, interface copy
Coding Guides	Crate layering, `RenderOnce` vs `Entity<T>`, state ownership, `ElementId`, events, focus, async, public API, naming, testing

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).

Section	Read when
Architecture at a glance	Always; crate layering, ownership boundary
Bootstrap and root ownership	`main`, `init`, `Root`, window creation, app-level state
Understand GPUI's phases and contexts	Anything touching `App`, `Window`, `Context<T>`, render vs update
Choose the right unit	Deciding `RenderOnce` vs `Entity<T>` vs custom `Element`
State ownership	Where a piece of state lives, who mutates it, `Entity<State>` handles
Stable identity	`ElementId`, lists, repeated elements, keyed state
Rendering and composition	`render`, builder chains, `when`/`map`, child composition
Behavior and presentation boundary	`gpui-base` vs `gpui-component` vs application code
Theme and styling	`cx.theme()`, tokens, `Styled`, sizes, variants
Events, actions, and focus	`cx.emit`, `subscribe`, `actions!`, keybindings, `FocusHandle`
Async work and side effects	`cx.spawn`, `background_spawn`, `Task`, I/O, timers
Layout, measurement, and scrolling	Flex layout, sizing, `overflow`, scroll handles, measuring
Lists, tables, and large data	`VirtualList`, `List`, `DataTable`, delegates, large collections
Public API design	Anything `pub`: builders, private fields, setter and reader naming
Platform and capability boundaries	macOS/Windows/Linux/wasm differences, feature gates
File and naming conventions	New files, modules, type and method names, `Kind` suffix, `Context`
Testing strategy	What to test, `#[gpui_kit::test]`, `TestAppContext`
Performance rules	Render cost, allocation, re-render triggers
Common failure modes	Before finishing; invented APIs, state in render, index ids
Rules for coding agents	Always when an agent writes code
Implementation checklist	Before finishing; run every item against the work

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

Component	Import	Notes
`Input`	`input::{Input, InputState}`	Stateful. Text, password, mask, validation
`Textarea`	`input::{Textarea, TextareaState}`	Stateful. Multi-line text
`Editor`	`input::{Editor, EditorState}`	Stateful. Code editor, `tree-sitter` feature
`NumberInput`	`input::{NumberInput, NumberInputEvent}`	Stateful. Numeric with step
`OtpInput`	`input::OtpInput`	Stateful. One-time password
`Select`	`select::{Select, SelectState}`	Stateful. Dropdown picker
`Combobox`	`combobox::{Combobox, ComboboxState}`	Stateful. Searchable select
`Checkbox`	`checkbox::Checkbox`	Stateless. `on_click` receives `&bool`
`Switch`	`switch::Switch`	Stateless. Toggle
`Radio`	`radio::{Radio, RadioGroup}`	Stateless.
`Slider`	`slider::{Slider, SliderState}`	Stateful.
`Toggle`	`button::Toggle`	Stateless.
`Rating`	`rating::Rating`	Stateless.
`Stepper`	`stepper::Stepper`	Stateless. Multi-step progress
`ColorPicker`	`color_picker::{ColorPicker, ColorPickerState}`	Stateful.
`DatePicker`	`date_picker::{DatePicker, DatePickerState}`	Stateful.
`Calendar`	`calendar::{Calendar, CalendarState}`	Stateful. Inline month view
`Form`	`form::{v_form, h_form, field}`	Layout container for form fields

Display & Feedback

Component	Import	Notes
`Button`	`button::{Button, ButtonGroup}`	Stateless. Primary UI action
`Icon`	`{Icon, IconName}`	Stateless. Lucide icons
`Badge`	`badge::Badge`	Stateless.
`Tag`	`tag::Tag`	Stateless. Closable tags
`Avatar`	`avatar::Avatar`	Stateless.
`Label`	`label::Label`	Stateless. Form label
`Kbd`	`kbd::Kbd`	Stateless. Keyboard key display
`Alert`	`alert::Alert`	Stateless. Info/success/warning/error
`Spinner`	`spinner::Spinner`	Stateless. Loading indicator
`Skeleton`	`skeleton::Skeleton`	Stateless. Loading placeholder
`Shimmer`	`shimmer::{ShimmerText, ShimmerStyle}`	Stateless. Streaming-text shimmer
`Marker`	`marker::{Marker, MarkerVariant}`	Stateless. Inline status marker
`Progress`	`progress::{Progress, ProgressCircle}`	Stateless.
`Tooltip`	`tooltip::Tooltip`	Via `.tooltip()` on elements
`HoverCard`	`hover_card::{HoverCard, HoverCardState}`	Stateful.
`Clipboard`	`clipboard::Clipboard`	Stateless. Copy button
`TextView`	`text::TextView`	`TextView::markdown(id, text)`, HTML too
Image	`gpui_kit::{img, ImageSource, ObjectFit}`	GPUI's `img()` element

Overlay & Popups

Component	Import	Notes
`Dialog`	`dialog::Dialog` + `WindowExt`	Via `window.open_dialog(...)`
`AlertDialog`	`WindowExt`	Via `window.open_alert_dialog(...)`
`Sheet`	`sheet::Sheet` + `WindowExt`	Side panel, via `window.open_sheet(...)`
`Notification`	`notification::Notification` + `WindowExt`	Via `window.push_notification(...)`
`Popover`	`popover::Popover`	Floating overlay
`Menu`	`menu::{PopupMenu, DropdownMenu}`	Context menus
`DropdownButton`	`button::DropdownButton`	Button with dropdown menu
`Command`	`command::{Command, CommandState, CommandGroup}`	Stateful. Command palette
Focus trap	`FocusTrapElement`	`.focus_trap(id, &handle)` on a container; `Dialog` and `Sheet` have it built in

Navigation & Layout

Component	Import	Notes
`Tabs` / `TabBar`	`tab::{Tab, TabBar}`	Tabbed interface
`Sidebar`	`sidebar::{Sidebar, SidebarMenu, ...}`	App navigation panel
`TitleBar`	`TitleBar`	Window title bar
`StatusBar`	`status_bar::StatusBar`	Window status bar
`Breadcrumb`	`breadcrumb::Breadcrumb`	Navigation breadcrumb
`Pagination`	`pagination::Pagination`	Page navigation
`Accordion`	`accordion::Accordion`	Collapsible sections
`Collapsible`	`collapsible::Collapsible`	Single collapsible
`GroupBox`	`group_box::GroupBox`	Labeled container
`Resizable`	`resizable::{h_resizable, v_resizable, resizable_panel, ResizableState}`	Draggable split panes
`Scrollbar`	`scroll::Scrollbar`	Custom scrollbar

Data Display

Component	Import	Notes
`DataTable`	`table::{DataTable, TableState, TableDelegate}`	Stateful. Full-featured table
`Table`	`table::{Table, ...}`	Simpler table
`VirtualList`	`{v_virtual_list, h_virtual_list}`	High-perf large lists
`List`	`list::{List, ListState, ListDelegate}`	Stateful. Searchable list
`Tree`	`tree::{Tree, TreeState, TreeItem, TreeEntry}`	Stateful. Hierarchy
`DescriptionList`	`description_list::DescriptionList`	Key-value pairs
`Settings`	`setting::Settings`	Settings panel

Chat & Messaging

Component	Import	Notes
`Message`	`message::{Message, MessageContent, MessageAlignment}`	Stateless. Chat message row
`Bubble`	`bubble::{Bubble, BubbleContent, BubbleVariant}`	Stateless. Message bubble
`Attachment`	`attachment::{Attachment, AttachmentContent, ...}`	Stateless. File/media attachment card
`MessageScroller`	`message_scroller::{MessageScroller, MessageScrollerState}`	Stateful. Auto-scrolling message list

Charts

Component	Import	Notes
`Chart`	`chart::{AreaChart, BarChart, LineChart, PieChart, RadarChart}`	Bar, line, area, pie charts
`Plot`	`plot::Plot`	`#[derive(IntoPlot)]` for data

GPUI References

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

Topic	File	Load when
Actions & keybindings	action.md	`actions!`, `bind_keys`, `on_action`, `key_context`
Async & background tasks	async.md	`cx.spawn`, `background_spawn`, `Task`, async I/O
Context management	context.md	`App`, `Window`, `Context<T>`, `AsyncApp`
Custom elements (low-level)	element.md	`Element` trait, `request_layout`, `prepaint`, `paint`
Entity state	entity.md	`Entity<T>`, `WeakEntity`, state management
Events & subscriptions	event.md	`cx.emit`, `cx.subscribe`, `cx.observe`
Focus & keyboard nav	focus-handle.md	`FocusHandle`, `track_focus`, Tab navigation
Global state	global.md	`Global` trait, `cx.set_global`, app-wide config
Layout & styling	layout-style.md	`div()`, `h_flex()`, `v_flex()`, flexbox, overflow, positioning
ElementId	element-id.md	`ElementId`, `.id()`, uniqueness rules, stateful elements
Testing	test.md	`#[gpui_kit::test]`, `TestAppContext`, `VisualTestContext`

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)

gpui-kit

About