Crate gpui_macos 

macOS’s presentation language on gpui-base’s interaction primitives.

Call init once, then use the constructors in controls and surface inside Render. They retain base builder APIs; Button adds disabled-state style gating.

gpui-macos

A macOS component library for GPUI Kit 0.7.1, with real AppKit toolbar chrome, runtime SF Symbols, measured control geometry, and glass navigation surfaces. The gallery contains 100 pages covering the full GPUI Kit component catalog and additional macOS layouts.

The design targets Apple’s macOS 27 design resources. The library follows the approach demonstrated by gpui-omarchy: custom presentation on gpui-base behavior. Native adapters cover controls, overlays, navigation, data views and seven chart types. Advanced components retain their complete GPUI Kit APIs through gpui_macos::kit and share the same theme.

Run

Install Rust through rustup and the Xcode command-line tools. The repository’s toolchain file selects the tested Rust version.

cargo run --example gallery
cargo run --example gallery -- button
cargo run --example gallery -- overview --light
cargo run --example gallery -- overview --dark
cargo run --example hello

On macOS, scripts/bundle-gallery.sh creates target/debug/GPUI macOS Gallery.app, which you can launch from Finder. Pass release to the script for a release build.

Use the sidebar to explore every component. The native appearance button cycles System, Dark and Light; the fallback Appearance menu lists each mode. Tab navigates controls; arrow keys navigate option groups and the sidebar. The toolbar’s zoom controls range from 50% to 200%.

Compare with real AppKit

The Swift reference uses real NSButton, NSSwitch, NSTextField, NSSegmentedControl, NSPopUpButton, NSSlider and NSTableView controls. The matching GPUI example uses this library’s public constructors.

scripts/build-native-reference.sh
scripts/bundle-native-compare.sh
cargo run --example native_compare -- --light
cargo run --example native_compare -- --dark

Launch target/native-reference/Native macOS Reference.app and target/debug/GPUI Native Compare.app from Finder. Both accept --light, --dark, and --page controls|workspace. The Swift reference also supports --page sidebar for the native navigation comparison, and --measure --metrics <path> without opening a window. Checked-in native measurements record macOS 26.2 intrinsic dimensions and light/dark semantic colors. See the interactive comparison for side-by-side and overlay views, with comparison notes describing remaining differences.

Add to an application

Add the published crate:

[dependencies]
gpui-macos = "0.1.1"

For development from a checkout, use gpui-macos = { path = "../gpui-macos" }.

The crate reexports its matching gpui-kit dependency, avoiding duplicate framework versions. The five pinned Kit crates are included under vendor/, with portable local dependencies and small Base extensions for secure masks and popup factories; consumer patch tables are unnecessary. See source provenance. This complete example uses native window controls and a Root host for overlays, focus, notifications and text selection:

use gpui_macos::{gpui_kit::*, *};

struct Hello { clicks: usize }

impl Render for Hello {
    fn render(&mut self, _: &mut Window, cx: &mut Context<Self>) -> impl IntoElement {
        focus_scope("hello")
            .size_full()
            .flex().flex_col()
            .child(title_bar("My Mac App", cx))
            .child(div().flex_1().p_6().bg(cx.macos().background).child(
                panel("Welcome", cx).child(
                    button("hello", format!("Clicked {} times", self.clicks),
                           ButtonVariant::Primary, cx)
                        .on_click(cx.listener(|this, _, _, cx| {
                            this.clicks += 1;
                            cx.notify();
                        })),
                ),
            ))
    }
}

fn main() {
    application().with_assets(NativeAssets::new(gpui_kit::assets::AllAssets)).run(|cx| {
        gpui_macos::init(cx);
        gpui_macos::open_window(gpui_macos::window_options("My Mac App", cx), cx,
            |_, cx| cx.new(|_| Hello { clicks: 0 }))
            .expect("open window");
        cx.activate(true);
    });
}

See examples/hello.rs and the complete gallery for runnable applications.

Components and state

The component index lists every preview, public API and upstream reference. catalog::COMPONENTS supplies typed metadata and catalog::COMPONENT_GROUPS supplies the same ordered groups used by the gallery.

Applications own checkbox, switch, radio, toggle and selection state. Pass the current value on each render, then update it in on_change or on_click. Editors, pickers, trees and virtual lists retain their Entity state. IDs must be stable and unique among siblings. Wrap a window’s controls in focus_scope for Tab traversal. Use open_window to install a Root host and appearance observation; applications using their own window host can call observe_window once and construct gpui_kit::base::Root themselves.

Use the native convenience constructors at the crate root. The complete advanced API is available under kit, for example kit::input::Input for a code editor, kit::table::DataTable for sortable virtual data tables, kit::diff::Diff, kit::command::Command, and kit::questionnaire::Questionnaire. Advanced component modules such as form, rating, carousel, message, spinner and notification are also reexported directly.

Appearance

init(cx) follows the system. An explicit theme applies to every window and the native window chrome:

Theme::light().apply(cx);
Theme::dark().with_accent(gpui_kit::rgb(0xaf52de).into())
    .with_glass_tint(0.8).apply(cx);
Theme::follow_system(cx);

The accent and material tint survive system appearance changes. The theme updates native adapters, GPUI Base semantic tokens and GPUI Kit resolved tokens together. Theme exposes color, font and material values for custom controls. Dimensions use rem units so interface zoom also scales control geometry. Call set_zoom(125, window, cx) to set a window to 125%; zoom_percent(window) reads it back. The Root host preserves this setting across renders and theme changes, with a supported range of 50% to 200%.

On macOS, system appearance reads Reduce transparency and Increase contrast. GPUI Base reads Reduce motion during initialization. Call refresh_accessibility(cx) after a runtime Display preference change to read these settings again. Applications can also apply explicit accessibility preferences with the theme builders or cx.set_reduce_motion(true).

Rendering and platform scope

These are GPUI-rendered controls, with native macOS visual conventions and shared keyboard, input, IME, clipboard and accessibility behavior. They are built on GPUI Kit interaction primitives. On macOS, the gallery and comparison app install an actual unified AppKit toolbar and native search. AppKit supplies its window corners and command glass. Sidebars use genuine NSGlassEffectView underlays on macOS 26 and newer. native_material(id, role, cx) and native_toolbar_group(id, cx) expose the same glass for application layouts.

Keep roots transparent and paint opaque backgrounds in content panes. Navigation underlays sample behind the window. Anchored popovers, menus, choice lists, date/color pickers and hover cards use retained content factories in separate GPUI popup windows inside real NSGlassEffectView surfaces. These can sample the GPUI canvas beneath them. Custom overlays can use native::open_glass_panel; build retained Render entities rather than passing frame-local elements between windows. Existing one-shot Base content builders retain inline presentation. Headless windows, older systems and Reduce Transparency use opaque fallbacks with the same interactions. Run scripts/bundle-glass-compare.sh for an interactive canvas comparison. Use native_window_options when installing native chrome. See native for the toolbar’s retained handle and native inset.

System fonts are resolved on the host; Apple fonts and SF Symbols are not bundled. Use NativeAssets::new(gpui_kit::assets::AllAssets) to supply runtime SF artwork to nested Kit icons as well as the macOS adapters. Unavailable symbols and custom assets delegate to the supplied source. The complete Lucide catalog remains available as fallback. The native gallery is validated on macOS 26.2, with macOS 27’s documented design as the target. Windows and Linux can render the design but have different window decoration and blur support.

Optional features:

Feature	Purpose
gpui-fast (default)	GPUI Fast renderer, matching the reference library
tree-sitter	Editor syntax-highlighting infrastructure
tree-sitter-languages	The upstream language bundle
speech	System speech input; uses the host’s microphone/recognizer permissions

The Speech gallery page explains the disabled feature and its supported platform path without requesting microphone access automatically.

Validation

cargo fmt --check
cargo check --all-targets --locked
cargo test --all-targets --locked
cargo test --doc --locked
cargo clippy --all-targets --locked -- -D warnings

Tests exercise pointer and keyboard activation, disabled state, focus traversal, editor affixes, grouped selections, dialogs, pickers, menus, animation and reduced motion. The gallery render sweep visits every catalog page in both appearances. CI runs on macOS. See design notes for boundaries.

License and credits

The implementation is MIT. The distributed package also includes an Apache-2.0 upstream source fixture, so its package metadata is MIT AND Apache-2.0. Behavioral adapters, the initial gallery, charts and the plot tooltip derive from Jason Lee’s MIT-licensed gpui-omarchy. See NOTICE and the license/source records. GPUI Kit and GPUI retain their Apache-2.0 licenses. Application bundles include dependency notices and MPL source archives. Apple is not affiliated with this library.

The root package remains gpui-macos; the five patched Kit packages use gpui-macos-* names with exact matching versions. See the publishing instructions for offline archive verification and dependency-ordered release commands.

Re-exports

pub use button::Button;

pub use button_group::button_group;

pub use button_group::tab_list;

pub use calendar::calendar;

pub use chart::AreaChart;

pub use chart::BarChart;

pub use chart::CandlestickChart;

pub use chart::LineChart;

pub use chart::PieChart;

pub use chart::RadarChart;

pub use chart::SankeyChart;

pub use color_picker::color_picker;

pub use date_picker::DatePickerState;

pub use date_picker::date_picker;

pub use dock::dock_area;

pub use fields::search_field;

pub use fields::secure_field;

pub use focus::focus_scope;

pub use hover_card::hover_card;

pub use icon::Icon;

pub use icon::icon;

pub use input::Input;

pub use input::input;

pub use input::number_input;

pub use input::textarea;

pub use link::Link;

pub use list::inset_list;

pub use list::inset_list_row;

pub use list::scrollbar;

pub use list::virtual_list;

pub use loading::native_spinner;

pub use menu::MenuItem;

pub use menu::menu;

pub use native_assets::NativeAssets;

pub use otp_input::OtpInput;

pub use otp_input::otp_input;

pub use popover::popover;

pub use popover::popover_surface;

pub use resizable::resizable;

pub use resizable::resizable_panel;

pub use select::ChoiceItem;

pub use select::ChoiceState;

pub use select::combobox;

pub use select::select;

pub use sheet::sheet;

pub use sheet::sheet_surface;

pub use slider::slider;

pub use text::html;

pub use text::markdown;

pub use text::text_view_style;

pub use theme::ActiveTheme;

pub use theme::Theme;

pub use tooltip::tooltip;

pub use tooltip::with_tooltip;

pub use tree::tree;

pub use window::set_zoom;

pub use window::zoom_percent;

pub use button_group::button_group as segmented_control;

pub use gpui_kit::component as kit;

pub use chrome::*;

pub use controls::*;

pub use dialog::*;

pub use navigation::*;

pub use surface::*;

pub use table::*;

Modules

attachment

breadcrumb

bubble

button

Button presentation that suppresses transient styles while disabled.

button_group

Exclusive settings and page navigation with one keyboard stop per group.

calendar

Calendar presentation over gpui-base’s date and view state.

carousel

catalog

Complete, discoverable component inventory used by the native gallery.

chart

chrome

Composable macOS window chrome, sidebars, inspectors and grouped settings.

clipboard

color_picker

Color editing backed by base’s hex validation and synchronized HSLA state.

command

A command palette: a search field over a filtered list of commands, with groups, Action keybinding hints and keyboard navigation.

controls

Styled constructors retain gpui-base’s controlled-state builder APIs.

date_picker

description_list

dialog

Modal presentation built from gpui-base’s dialog hosts and content slots.

diff

Readonly, virtualized patch display inspired by Diffs from Pierre. Parse an externally supplied patch into DiffFiles, retain one DiffState for all of them in the owner, and build Diff during rendering.

dock

Dock presentation. Layout, reconciliation and drag operations stay in base.

fields

Familiar macOS text-field configurations on the shared editor behavior.

focus

Keyboard traversal for a composed desktop region.

form

group_box

hover_card

icon

Native SF Symbols on macOS, with the complete Lucide catalog as fallback.

input

Native text editing, selection, clipboard and IME supplied by gpui-base.

interpretation

Auditable macOS presentation contract for the complete component catalog.

label

link

Link presentation that suppresses transient styles while disabled.

list

Virtualized lists retain base’s sizing and scroll model.

loading

The radial macOS activity indicator on GPUI Kit’s animation primitive.

marker

menu

A keyboard menu composed from the base Popover and Button primitives.

message

message_scroller

native

Optional AppKit chrome and material hosting for macOS windows.

native_assets

Runtime SF Symbols for both macOS adapters and upstream GPUI Kit icons.

navigation

Composable section navigation with gpui-base state and accessibility.

notification

otp_input

plot

Plotting for macOS charts.

popover

Contextual controls in an anchored, non-modal surface.

questionnaire

Composable questionnaire controls.

rating

resizable

select

Select and searchable Combobox presentations over the controlled base roots.

setting

sheet

Edge-attached modal details, with dismissal and focus trapping owned by base.

shimmer

skeleton

slider

Horizontal single-value and range sliders with native pointer interaction. The rounded track follows pointer drags exactly and eases keyboard changes.

speech

Speech input: capture audio, recognize it and hand the text to the caller.

spinner

surface

Rounded content surfaces and non-interactive information components.

table

Primitive tables: application-owned columns, rows and content.

tag

text

Read-only rich text using base’s Markdown and HTML renderers.

theme

macOS semantic colors, typography, geometry, and material preferences.

time_field

tooltip

Short, non-interactive explanations with GPUI’s tooltip lifecycle.

tree

window

Window presentation shared by the native and advanced component layers.

Macros

impl_into_plot

Make a Plot usable as a child element.

Enums

IconName

Names of all bundled Lucide and GPUI Kit icons.

Functions

application

Create an application using the current desktop platform.

init

Initialize all behavior, native adapters, and system appearance once at startup.

native_window_options

Window settings for an AppKit toolbar and native glass underlays. Use with native::install_native_toolbar. AppKit places the traffic lights; transparent renderer regions reveal system glass without a legacy blur layer.

observe_window

Follow macOS light/dark changes for this window. The observer lives with it. Repeated calls on the same window do not install duplicate subscriptions.

open_window

Open a Root-hosted window and install appearance observation automatically. Root provides the overlay, notification, focus and text-selection services.

refresh_accessibility

Re-read Display accessibility preferences after an application settings change.

window_options

Native window settings with real system traffic lights and a blurred backdrop. Place a title_bar at the top of the content when using this configuration.