gpui-omarchy
gpui-omarchy is a gpui-kit component library designed specifically for the Omarchy system. It follows Omarchy’s UI and UX conventions, helping developers build desktop applications that feel at home in Omarchy.
The library brings Omarchy’s system themes, restrained visual style and keyboard-first interactions to reusable GPUI components. Built on gpui-base, it combines Omarchy presentation with shared focus, input, accessibility and composition primitives.
It also serves as a practical proving ground for gpui-base’s customization capabilities: building a complete Omarchy design system tests how freely applications can define their own visual identity and interaction patterns on top of base primitives. The project demonstrates that a shared behavioral foundation can support a fully custom design language, while exposing gaps to improve in gpui-base.
The project is under development, with 54 component previews in one gallery. Form, navigation, overlay and data components are still being expanded; the framework is not yet complete.
Running the gallery
Install Rust and the platform-specific build dependencies required by GPUI. The gallery uses .SystemUIFont, so no additional fonts are needed. Icons use SVGs from gpui-kit-assets, with inherited colors resolved during rendering. Register gpui_kit::assets::Assets on the application, as shown in the examples.
cargo run --example gallery
The single gallery example groups components under Actions, Forms, Navigation, Overlays, Display and Charts. Choose a component in the sidebar to inspect and interact with it. Use Up/Down, j/k or Home/End to navigate the sidebar, and Tab to enter the controls. The top Menu reloads the system theme, previews dark or light colors, and exits the gallery.
Use the top-bar − / + controls to test interface zoom from 50% to 200% in 25% steps. Click the percentage to reset to 100%, or use Cmd/Ctrl + +, -, and 0. Zoom updates the window's rem size, including list measurements, and persists while switching components and themes in the same window.
UI typography, spacing, icon sizes and control dimensions use rem units and follow Window::rem_size(). Pixel-only base APIs (scrollbars, rich-text headings, resizable panels and virtual-list measurements) resolve rem dimensions with the current window. scrollbar, markdown, html and text_view_style therefore take window: &Window before cx. Physical borders, native window bounds, test pointer coordinates and the base theme's nominal typography snapshot remain pixel-based.
Themes
gpui_omarchy::init(cx) initializes base and first reads:
$HOME/.local/state/omarchy/current/theme/colors.toml
$HOME/.local/state/omarchy/current/theme.name
If the current directory does not exist, the loader supports the legacy $HOME/.config/omarchy/current location. If the current directory exists but its theme is invalid, it falls back to Tokyo Night without loading a stale legacy theme.
Both ANSI color0..15 and semantic Omarchy color formats are supported. Missing files, insufficient permissions, invalid formats or missing required colors cause the entire palette to fall back to Tokyo Night. Non-Omarchy systems require no configuration.
Theme locations and the theme-name file follow the Omarchy theme-set script. See the ANSI theme and semantic theme for color formats.
Native applications follow the system theme after init: filesystem events detect palette edits and theme symlink replacements, and all windows update only when the theme changes. Applying an explicit theme with Theme::apply(cx) stops following; Theme::follow_system(cx) resumes it. Theme::system_or_default() remains a one-time snapshot. Theme::follow_system(cx) does nothing in browsers; initialization still supplies the default palette. shell.toml size and state overrides are not yet implemented. Flexoki Light is available for previewing light colors; the gallery follows the system theme by default.
Usage
Read the single-page Guides for application setup, state, themes, forms, navigation, overlays and data views, with API details alongside each task.
Add the library to your application:
[dependencies]
gpui-kit = { version = "=0.7.0", default-features = false }
gpui-omarchy = "0.2.0"
Use gpui_kit for framework types, gpui_kit::application() for the desktop entry point, and gpui_kit::base for base state and composition APIs. GPUI Kit’s component facade is disabled so gpui-omarchy supplies the presentation. See the complete quick start.
Call gpui_omarchy::init(cx) once at startup, then create components inside Render:
use gpui_kit::ParentElement;
use gpui_omarchy::{button, panel, ButtonVariant};
panel("Workspace", cx).child(
button("save", "Save", ButtonVariant::Primary, cx)
.on_click(cx.listener(|this, _, _, cx| {
this.save();
cx.notify();
})),
)
Constructors return composable gpui-base elements with their native builder APIs. Button uses a thin gpui_omarchy::Button wrapper that retains base activation, focus, children and styling APIs while withholding hover, pressed and focus-visible styles when disabled. Calling .disabled(true) before or after styling has the same result. gpui_omarchy::Link likewise suppresses hover, pressed and focus-visible styling when disabled, while retaining base URL activation behavior. Applications own checkbox, switch, radio and toggle state: pass the current value on each render and update it in on_change. Avoid overriding these values after construction, which can leave visual indicators out of sync. Component IDs must be unique within the same parent.
Select and Combobox use an application-owned Entity<ChoiceState> and ChoiceItem options. Observe changes with cx.observe, then read the selected option's stable value through state.selected(). The constructors return customizable gpui_kit::base::Select and gpui_kit::base::Combobox elements. Combobox searches existing options in its popup; it does not create free-text values.
Wrap a window or form in focus_scope("app") to enable Tab and Shift+Tab traversal. Text fields and popups retain their own keyboard behavior.
toggle_group(id, cx) composes independent toggle children for multiple-choice filters. Add icons explicitly through child elements.
button_group(...) represents a single-choice setting with equal-width segments; tab_list(...) switches between content pages in a segmented strip. Both accept ChoiceItem options, the selected index and a callback, returning base RadioGroup and Tabs respectively. tab_list also takes show_shortcuts: bool after the selected index: use false for labels only, or true for automatic one-based number hints (applications own key bindings). Each group has one Tab stop. Left/Right or h/l moves the cursor, and Enter or Space confirms. Use tabs and tab for custom compositions.
input(...) returns an Input supporting .prefix(element) and .suffix(element) for text, icons or custom content within the input border. Both slots are empty by default and do not change the editable value.
with_tooltip(control, "Description") preserves the control's type and adds a tooltip after 400 ms of hovering. tooltip(text, cx) returns a customizable tooltip surface. Icon buttons still need explicit accessible names.
sheet(&focus, cx) returns a base Sheet. Compose its right-side panel with .surface(sheet_surface(cx).child(...)). Focus a stable handle when opening and restore trigger focus in the close callback. Base handles focus trapping, Escape and backdrop dismissal.
popover returns a base Popover with square styling and keyboard isolation inside its content. Escape dismisses it and restores focus. collapsible(open, cx) returns a base Collapsible: regular children remain visible, while its content appears only when expanded.
toast(id, cx) returns a composable base Toast surface. Applications control its lifecycle, optionally using base ToastManager. The gallery displays notifications at the bottom right with Undo and Retry actions. Saved notifications expire after six seconds, with the timer paused during hover or focus; errors remain until handled manually.
alert(message, status, cx) renders an inline feedback banner with a status icon and themed styling for persistent conditions, unlike alert_dialog, which presents an explicit-decision modal.
avatar(initials, cx) returns a square base Avatar. Set its image slot with .image(avatar_image(source)). The application decides whether to fall back to initials when image loading fails.
calendar(id, &state, cx) uses base CalendarState, with month/year navigation, single-date or range selection and disabled-date matchers. separator and vertical_separator provide horizontal and vertical dividers.
scrollbar(id, axis, &handle, window, cx) returns a themed base Scrollbar. Share its handle with the scrollable content and render it last inside the same relative container. Vertical, horizontal and both-axis configurations are supported.
virtual_list(view, id, sizes, render, cx) returns a base VirtualList that builds only the visible range. Each height in sizes must match the corresponding rendered row. Use .track_scroll(&handle) to preserve position or navigate to an item. The gallery displays 1,000 activity records with varying heights.
markdown(id, source, window, cx) and html(id, source, window, cx) return base TextView elements with selectable text, links and themed document typography. State-backed TextViews can use text_view_style(window, cx). Selection uses the application's root TextSelectionLayer.
tree(&state, cx) uses base TreeState. resizable(id, axis, cx) returns a base split container, with dragging and size constraints handled by base. nav_stack(&state, cx) preserves base push, pop and forward navigation state.
color_picker(id, &state, window, cx) uses base ColorPickerState with Hex input and HSLA sliders. Enter commits Hex input; Escape discards an uncommitted preview. Sliders apply immediately. Observe the state or subscribe to ColorPickerEvent to update application previews.
date_picker(id, &state, cx) uses DatePickerState. Its public calendar state supports ranges and disabled dates. Selecting a date closes the popup; Escape cancels and restores focus. otp_input uses base OtpState with an Omarchy wrapper for system clipboard paste and disabled interaction. Pasting replaces the code, filters non-digits, normalizes full-width digits, and truncates to the configured length.
hover_card provides a delayed supplementary preview; essential content should also be accessible on the main page. dock_area installs the Omarchy DockAreaRenderer. Its example demonstrates dragging, merging and splitting tabbed panels. Docking supports tabs and split layouts; floating layouts are not offered.
Input state uses gpui_kit::base::input::{InputState, TextareaState}. See the gallery implementation for initialization examples.
Validation
cargo fmt --check
cargo check --all-targets
cargo test --lib --test interaction --example gallery
Implementation boundaries and remaining work are recorded in the design notes.
If the gallery panics, it writes the error location and full backtrace to gpui-omarchy-gallery-<PID>.panic.log in the system temporary directory. The terminal also prints the report path. This diagnostic logging is limited to the example application.
Website
The website presents GPUI Kit, gpui-base, and Omarchy Style with the actual Rust gallery compiled to WebAssembly and Cargo installation instructions. Built with Bun, Astro, Tailwind CSS, and Base UI.
Install the WASM build tools, then run:
bash examples/gallery-wasm/scripts/build.sh --release
cd website
bun install
bun run dev
Publishing
The Publish crate workflow publishes to crates.io when a v* tag is pushed. It checks that the tag exactly matches v followed by the version in Cargo.toml, runs formatting and tests, and verifies the package with cargo publish --dry-run before uploading.
Set the repository Actions secret CARGO_REGISTRY_TOKEN to a crates.io API token with permission to publish gpui-omarchy. The token is only passed to the final publish step.
To release:
-
Update version in Cargo.toml and regenerate Cargo.lock with cargo check.
-
Commit and push the release changes, including the workflow.
-
Create and push the matching tag, for example:
git tag v0.1.0
git push origin v0.1.0
Use a new version for each release; crates.io does not allow replacing an existing version. A tag/version mismatch or failed check stops publication.
Users
License
MIT © 2026 Jason Lee (huacnlee).
