egui-macview

Native-style macOS AppKit controls, layouts, and smooth spring animations for egui on Windows, macOS, Linux, and Web.

Why egui-macview?

Standard egui is great for quick tools and game overlays, but building a desktop application that feels like a native macOS app (such as Xcode, Final Cut Pro, Finder, or System Settings) requires predictable widget dimensions, crisp 1px borders, keyboard navigation, and smooth animations.

egui-macview gives you a ready-to-use library of 35+ macOS AppKit and AVKit controls built directly on egui 0.37:

• Measured on real macOS hardware: Control heights, padding insets, corner radii, and colors are measured directly from macOS Sonoma (AppKit and AVKit) so your UI looks right out of the box.
• Light, Dark, and Anthracite themes: Switch seamlessly between MacAppearance::Aqua (Light), MacAppearance::DarkAqua (Dark), and MacAppearance::Anthracite, with automatic WCAG contrast handling for custom accent colors.
• Battery-friendly by design: Zero background repaints when idle, automatic animation pausing when the window is unfocused or minimized, and 2D viewport culling for large tables and grids.
• Cross-platform vector icons: Includes an embedded CupertinoIcons TrueType font so symbols look identical on Windows, macOS, Linux, and Web without relying on OS emojis.

Installation

Add egui-macview to your Cargo.toml:

[dependencies]
egui = "0.37.0"
egui-macview = "0.6.11"

To run the interactive showcase gallery included in this repository:

cargo run --example macview_gallery

Your First App in 60 Seconds (eframe)

Here is a complete, runnable desktop application (src/main.rs) with a macOS window toolbar, a resizable sidebar split view, and a two-column settings form:

use eframe::egui;
use egui_macview::{
    MacAppearance, MacBox, MacButton, MacForm, MacInputCell, MacSegmentedControl,
    MacSplitOrientation, MacSplitView, MacTheme, MacToggle, MacToolbar, WindowControlsStyle,
    setup_symbols_font,
};

struct MyMacApp {
    appearance: MacAppearance,
    sidebar_width: f32,
    project_name: String,
    auto_save: bool,
    view_mode: usize,
}

impl Default for MyMacApp {
    fn default() -> Self {
        Self {
            appearance: MacAppearance::DarkAqua,
            sidebar_width: 200.0,
            project_name: String::from("Untitled Studio Project"),
            auto_save: true,
            view_mode: 0,
        }
    }
}

impl eframe::App for MyMacApp {
    fn ui(&mut self, ui: &mut egui::Ui, _frame: &mut eframe::Frame) {
        let theme = MacTheme::new(self.appearance);
        theme.apply_to_egui(ui.ctx());

        // Top window toolbar
        MacToolbar::new("My Studio App")
            .window_controls_style(WindowControlsStyle::AppleTrafficLights)
            .theme(&theme)
            .show(ui, |toolbar_ui| {
                let modes = ["Editor", "Inspector"];
                MacSegmentedControl::new(&modes, self.view_mode)
                    .theme(&theme)
                    .show(toolbar_ui, |idx| self.view_mode = idx);

                let label = match self.appearance {
                    MacAppearance::Aqua => "Switch to Dark",
                    _ => "Switch to Light",
                };
                if toolbar_ui.add(MacButton::new(label).theme(&theme)).clicked() {
                    self.appearance = match self.appearance {
                        MacAppearance::Aqua => MacAppearance::DarkAqua,
                        _ => MacAppearance::Aqua,
                    };
                }
            });

        // Main split view with sidebar and inspector form
        MacSplitView::with_pos(
            "workspace_split",
            MacSplitOrientation::Horizontal,
            &mut self.sidebar_width,
        )
        .min_first(150.0)
        .max_first(320.0)
        .theme(&theme)
        .show(
            ui,
            |sidebar_ui| {
                sidebar_ui.heading("Project Files");
                sidebar_ui.label("• main.rs");
                sidebar_ui.label("• Cargo.toml");
            },
            |content_ui| {
                MacBox::new("Project Preferences")
                    .theme(&theme)
                    .show(content_ui, |box_ui| {
                        MacForm::new("prefs_form").theme(&theme).show(box_ui, |form| {
                            form.row_label("Project Name:", |ui| {
                                MacInputCell::new("proj_name", &mut self.project_name)
                                    .theme(&theme)
                                    .show(ui);
                            });
                            form.row_label("Auto-Save:", |ui| {
                                ui.add(MacToggle::new(&mut self.auto_save).theme(&theme));
                            });
                        });
                    });
            },
        );
    }
}

fn main() -> eframe::Result<()> {
    let options = eframe::NativeOptions::default();
    eframe::run_native(
        "My Studio App",
        options,
        Box::new(|cc| {
            // Register the embedded Cupertino vector icon font once at startup:
            let mut fonts = egui::FontDefinitions::default();
            setup_symbols_font(&mut fonts);
            cc.egui_ctx.set_fonts(fonts);
            Ok(Box::new(MyMacApp::default()))
        }),
    )
}

Quick Start & Copy-Paste Examples

Every control in egui-macview works with standard egui::Ui and optionally accepts a [MacTheme]. If you call theme.apply_to_egui(ctx) once when your app starts (or when the theme changes), widgets will automatically pick up your active theme even if you omit .theme(&theme).

1. Theme Setup, Buttons, Toggles & Segmented Controls

use egui_macview::{
    MacAppearance, MacButton, MacSegmentedControl, MacSymbol, MacTheme, MacToggle, SegmentItem,
    setup_symbols_font,
};

# let ctx = egui::Context::default();
// Call once at startup to register the monochrome Cupertino vector icon font:
let mut fonts = egui::FontDefinitions::default();
setup_symbols_font(&mut fonts);
ctx.set_fonts(fonts);

// Create a macOS theme (Aqua for Light mode, DarkAqua for Dark mode)
let theme = MacTheme::new(MacAppearance::DarkAqua);
theme.apply_to_egui(&ctx);

# let mut output = ctx.run_ui(egui::RawInput::default(), |ui| {
let mut auto_save = true;
let mut active_tool = 0usize;

ui.horizontal(|ui| {
    // macOS pill toggle switch (NSSwitch)
    ui.label("Auto-Save:");
    ui.add(MacToggle::new(&mut auto_save).theme(&theme));

    // Segmented strip with vector icons, per-segment widths & submenus (NSSegmentedControl)
    let tools = [
        SegmentItem::from_symbol(MacSymbol::Search).with_width(30.0).with_tooltip("Inspect"),
        SegmentItem::from_symbol(MacSymbol::Sliders).with_width(34.0).with_submenu(true),
        SegmentItem::new("Preview"),
    ];
    MacSegmentedControl::with_custom_segments(tools, active_tool)
        .id_salt("inspector_tools")
        .accessibility_label("Inspector Tools")
        .theme(&theme)
        .show_with_events(ui, |ev| {
            if ev.opens_menu() {
                // Open segment submenu anchored at ev.rect
            } else {
                active_tool = ev.index;
            }
        });

    // Momentary < | > navigation strip (NSSegmentedSwitchTrackingMomentary)
    MacSegmentedControl::momentary([SegmentItem::new("<"), SegmentItem::new(">")])
        .id_salt("history_nav")
        .theme(&theme)
        .show_momentary(ui, |_dir| {});

    // Push button (NSButton)
    if ui.add(MacButton::new("Apply").selected(true).theme(&theme)).clicked() {
        // Handle click
    }
});
# });
# output.textures_delta.clear();

2. Forms, Text Inputs, Search Fields, Sliders & Steppers

Use [MacForm] for clean two-column macOS preference panes with right-aligned labels and left-aligned controls:

use egui_macview::{
    MacAppearance, MacForm, MacInputCell, MacSearchField, MacSlider, MacStepper, MacTheme,
};

# let ctx = egui::Context::default();
# let mut output = ctx.run_ui(egui::RawInput::default(), |ui| {
let theme = MacTheme::new(MacAppearance::Aqua);
let mut project_name = String::from("Untitled Project");
let mut search_query = String::new();
let mut zoom_percent = 100.0f64;
let mut export_quality = 80.0f32;

// Search bar with magnifying glass icon and instant clear (×) button:
MacSearchField::new(&mut search_query)
    .placeholder("Filter settings...")
    .theme(&theme)
    .show(ui);

// Two-column macOS Settings form:
MacForm::new("project_settings_form")
    .theme(&theme)
    .show(ui, |form| {
        form.row(
            |ui| { ui.label("Project Name:"); },
            |ui| {
                MacInputCell::new("project_name_input", &mut project_name)
                    .theme(&theme)
                    .show(ui);
            },
        );

        form.row(
            |ui| { ui.label("Canvas Zoom:"); },
            |ui| {
                ui.horizontal(|ui| {
                    MacStepper::new(&mut zoom_percent, 25.0..=400.0, 25.0)
                        .theme(&theme)
                        .show(ui);
                    ui.label(format!("{zoom_percent:.0}%"));
                });
            },
        );

        form.row(
            |ui| { ui.label("Export Quality:"); },
            |ui| {
                MacSlider::new(&mut export_quality, 0.0..=100.0)
                    .ticks(5, true)
                    .theme(&theme)
                    .show(ui);
            },
        );
    });
# });
# output.textures_delta.clear();

3. Dropdowns & Searchable Combo Boxes (MacComboBox & MacPopUpButton)

Use [MacPopUpButton] when the user picks from a fixed list, or [MacComboBox] when they can both type to filter and pick from a dropdown list:

use egui_macview::{MacAppearance, MacComboBox, MacPopUpButton, MacTheme};

# let ctx = egui::Context::default();
# let mut output = ctx.run_ui(egui::RawInput::default(), |ui| {
let theme = MacTheme::new(MacAppearance::Aqua);

// 1. Fixed selection menu (NSPopUpButton)
let formats = ["PNG (Lossless)", "JPEG (Compressed)", "SVG (Vector)", "PDF (Print)"];
let mut selected_format = 0usize;
MacPopUpButton::new(&mut selected_format, &formats)
    .theme(&theme)
    .show(ui);

// 2. Editable + filterable combo box (NSComboBox)
let mut selected_font = String::from("SF Pro Text");
let fonts = ["Helvetica Neue", "Menlo", "New York", "SF Mono", "SF Pro Display", "SF Pro Text"];
MacComboBox::new("font_family_combo", &mut selected_font, &fonts)
    .width(200.0)
    .theme(&theme)
    .show(ui);
# });
# output.textures_delta.clear();

4. Date & Time Picker (MacDatePicker)

[MacDatePicker] supports both a compact text field with an integrated stepper (TextFieldAndStepper, where users can click year/month/day segments and use arrow keys) and a visual month calendar grid with an analog clock (ClockAndCalendar):

use egui_macview::{
    MacAppearance, MacDate, MacDatePicker, MacDatePickerElementFlags, MacDatePickerStyle, MacTheme,
};

# let ctx = egui::Context::default();
# let mut output = ctx.run_ui(egui::RawInput::default(), |ui| {
let theme = MacTheme::new(MacAppearance::Aqua);
let mut scheduled_at = MacDate {
    year: 2026,
    month: 11,
    day: 10,
    hour: 14,
    minute: 30,
    second: 0,
};

// Compact date & time field with up/down stepper arrows:
ui.add(
    MacDatePicker::new()
        .date(&mut scheduled_at)
        .style(MacDatePickerStyle::TextFieldAndStepper)
        .elements(MacDatePickerElementFlags::DateAndTime)
        .theme(&theme),
);

// Visual month calendar grid + 12-hour analog clock:
ui.add(
    MacDatePicker::new()
        .date(&mut scheduled_at)
        .style(MacDatePickerStyle::ClockAndCalendar)
        .elements(MacDatePickerElementFlags::DateAndTime)
        .theme(&theme),
);
# });
# output.textures_delta.clear();

5. Layout Containers: Tabs, Collapsible Disclosure Groups, Boxes & Split Views

Organize complex inspector panels and multi-pane windows with [MacTabView], [MacDisclosureGroup], [MacBox], and [MacSplitView]:

use egui_macview::{
    MacAppearance, MacBox, MacDisclosureGroup, MacSplitOrientation, MacSplitView, MacTabView,
    MacTheme,
};

# let ctx = egui::Context::default();
# let mut output = ctx.run_ui(egui::RawInput::default(), |ui| {
let theme = MacTheme::new(MacAppearance::DarkAqua);
let mut active_tab = 0usize;
let mut show_advanced = true;
let mut sidebar_width = 200.0f32;

// 1. Tabbed container (NSTabView)
MacTabView::new(&mut active_tab)
    .theme(&theme)
    .tab("General", |ui| {
        ui.label("General application settings");
    })
    .tab("Shortcuts", |ui| {
        ui.label("Keyboard shortcut bindings");
    })
    .show(ui);

// 2. Collapsible section with animated disclosure triangle
MacDisclosureGroup::new("advanced_options", "Advanced Export Options", &mut show_advanced)
    .theme(&theme)
    .show(ui, |ui| {
        MacBox::new("Color Profile")
            .theme(&theme)
            .show(ui, |ui| {
                ui.label("Display P3 Wide Gamut");
            });
    });

// 3. Resizable two-pane split view (NSSplitView)
MacSplitView::with_pos("main_split", MacSplitOrientation::Horizontal, &mut sidebar_width)
    .min_first(140.0)
    .max_first(360.0)
    .theme(&theme)
    .show(
        ui,
        |left_ui| {
            left_ui.label("Sidebar Navigation");
        },
        |right_ui| {
            right_ui.label("Main Editor Canvas");
        },
    );
# });
# output.textures_delta.clear();

6. Data Views: Multi-Column Tables, 2D Grids, Breadcrumb Path Bars & Rule Editors

Render large datasets smoothly with [MacTableView] and [MacCollectionView] (both use viewport culling so off-screen rows/tiles cost zero CPU time):

use std::collections::BTreeSet;
use egui_macview::{
    MacAppearance, MacCollectionView, MacCollectionViewFlowLayout, MacPathComponent,
    MacPathControl, MacRuleEditor, MacRuleRow, MacSortDirection, MacTableColumn, MacTableView,
    MacTheme, MacTokenField,
};

# let ctx = egui::Context::default();
# let mut output = ctx.run_ui(egui::RawInput::default(), |ui| {
let theme = MacTheme::new(MacAppearance::Aqua);

// 1. Finder-style breadcrumb bar (NSPathControl)
let path = [
    MacPathComponent::folder("Projects"),
    MacPathComponent::folder("egui-macview"),
    MacPathComponent::file("Cargo.toml"),
];
MacPathControl::new("project_path", &path)
    .theme(&theme)
    .show(ui);

// 2. Multi-column sortable table (NSTableView)
let mut columns = vec![
    MacTableColumn::new("Name", 180.0).sort(Some(MacSortDirection::Ascending)),
    MacTableColumn::new("Kind", 100.0),
];
let rows = [("README.md", "Markdown"), ("Cargo.toml", "TOML")];
let mut selected_rows = BTreeSet::from([0usize]);

MacTableView::new("files_table", &mut columns, rows.len(), &mut selected_rows)
    .theme(&theme)
    .show(ui, |cell_ui, row_idx, col_idx| {
        let (name, kind) = rows[row_idx];
        cell_ui.label(if col_idx == 0 { name } else { kind });
    });

// 3. 2D Grid Collection View (NSCollectionView) with viewport culling & marquee selection
let glyphs = ["A", "B", "C", "D", "E", "F"];
let mut selected_tiles = BTreeSet::from([0usize]);
MacCollectionView::new(&glyphs, &mut selected_tiles)
    .layout(MacCollectionViewFlowLayout::default())
    .theme(&theme)
    .show_with_response(ui, |tile_ui, glyph| {
        tile_ui.centered_and_justified(|ui| {
            ui.label(*glyph);
        });
    });

// 4. Tag pill input (NSTokenField) & Predicate filter builder (NSRuleEditor)
let mut tags = vec!["rust".to_string(), "gui".to_string()];
let mut tag_draft = String::new();
MacTokenField::new("topic_tags", &mut tags, &mut tag_draft)
    .placeholder("Add tag...")
    .theme(&theme)
    .show(ui);

let mut rules = vec![MacRuleRow::new(vec![0, 0, 0])];
let criteria: &[&[&str]] = &[
    &["Name", "Extension", "Modified Date"],
    &["contains", "begins with", "is"],
    &["rs", "toml", "md"],
];
MacRuleEditor::new("smart_filter", &mut rules, criteria)
    .theme(&theme)
    .show(ui);
# });
# output.textures_delta.clear();

7. Media Player Overlay, Timeline Scrubber, Audio Meters & Rotary Dials

Build audio/video players and studio interfaces with [MacPlayerView], [MacTrimScrubber], [MacLevelIndicator], [MacCircularSlider], and [MacRatingIndicator]:

use egui_macview::{
    MacAppearance, MacCircularSlider, MacLevelIndicator, MacLevelIndicatorStyle,
    MacPlayerControlsStyle, MacPlayerView, MacRatingIndicator, MacTheme, MacTrimScrubber,
};

# let ctx = egui::Context::default();
# let mut output = ctx.run_ui(egui::RawInput::default(), |ui| {
let theme = MacTheme::new(MacAppearance::DarkAqua);
let mut is_playing = false;
let mut progress = 0.25f32;
let mut volume = 0.8f32;
let mut playhead = 5.0f64;
let mut trim_in = 2.0f64;
let mut trim_out = 18.0f64;
let mut pan_dial = 0.0f32;
let mut rating = 4u32;

// 1. QuickTime floating HUD media player overlay (AVPlayerView)
ui.add(
    MacPlayerView::new()
        .controls_style(MacPlayerControlsStyle::Floating)
        .is_playing_mut(&mut is_playing)
        .progress_mut(&mut progress)
        .volume_mut(&mut volume)
        .duration_secs(60.0)
        .theme(&theme),
);

// 2. QuickTime yellow trim bar with waveform envelope (MacTrimScrubber)
let waveform = [0.2, 0.5, 0.8, 0.6, 0.9, 0.4, 0.7, 0.3];
MacTrimScrubber::new("clip_trim", 20.0, &mut trim_in, &mut trim_out, &mut playhead)
    .waveform(&waveform)
    .theme(&theme)
    .show(ui);

// 3. Rotary pan knob, VU level meter & 5-star rating indicator
ui.horizontal(|ui| {
    ui.add(MacCircularSlider::new(&mut pan_dial, -1.0..=1.0).theme(&theme));
    MacLevelIndicator::new(0.72, 0.0..=1.0)
        .style(MacLevelIndicatorStyle::Discrete)
        .peak_hold(0.88)
        .theme(&theme)
        .show(ui);
    ui.add(MacRatingIndicator::new(&mut rating, 5).theme(&theme));
});
# });
# output.textures_delta.clear();

Component Reference

Layout Containers (src/layout/ & src/controls/)

Controls & Data Views (src/controls/)

Navigation, Surfaces & State (src/navigation/, src/surfaces/, src/state/)

When to Use Which Control (Decision Guide)

Not sure which widget fits your screen best? Use these guidelines modeled after Apple's macOS Human Interface Guidelines:

1. Choosing a Selection Control

2. Choosing a Data View

3. Choosing a Layout Container

4. Choosing a Numeric Input

Troubleshooting & FAQ

1. Why do icons or symbols show up as empty boxes (□)?

egui-macview uses an embedded monochrome vector icon font (CupertinoIcons.ttf) so symbols render identically on Windows, macOS, Linux, and Web. You must register this font once on your egui::Context at startup:

use egui_macview::setup_symbols_font;

# let ctx = egui::Context::default();
let mut fonts = egui::FontDefinitions::default();
setup_symbols_font(&mut fonts);
ctx.set_fonts(fonts);

2. How do I switch dynamically between Light (Aqua), Dark (DarkAqua), and Anthracite themes?

Create a [MacTheme] with your chosen [MacAppearance] and call theme.apply_to_egui(ctx). Calling apply_to_egui updates egui's background visuals and stores the theme inside egui::Context so every egui-macview widget automatically uses it:

use egui_macview::{MacAppearance, MacButton, MacTheme};

# let ctx = egui::Context::default();
let theme = MacTheme::new(MacAppearance::Anthracite);
theme.apply_to_egui(&ctx);

# let mut out = ctx.run_ui(egui::RawInput::default(), |ui| {
// Because `apply_to_egui` was called, widgets automatically pick up `Anthracite`
// even when you don't pass `.theme(&theme)` explicitly:
ui.add(MacButton::new("Automatically Themed"));
# });
# out.textures_delta.clear();

3. How do I avoid widget ID collisions when rendering controls in a for loop?

Just like standard egui, stateful controls (MacComboBox, MacTableView, MacDisclosureGroup, MacInputCell, MacRuleEditor) use an ID salt to store popup or focus state across frames. When rendering multiple instances in a loop, either pass a unique tuple (name, index) as the ID salt or wrap each iteration in ui.push_id:

use egui_macview::MacComboBox;

# let ctx = egui::Context::default();
# let mut out = ctx.run_ui(egui::RawInput::default(), |ui| {
let options = ["None", "Fade", "Dissolve"];
let mut row_values = vec![String::from("Fade"), String::from("None")];

for (row_idx, val) in row_values.iter_mut().enumerate() {
    // Pass `("transition_combo", row_idx)` so each row gets a distinct egui::Id:
    MacComboBox::new(("transition_combo", row_idx), val, &options).show(ui);
}
# });
# out.textures_delta.clear();

4. How does battery-saving idle repaint work?

Immediate-mode GUIs often burn CPU and laptop battery by repainting at 60–120 FPS even when nothing is moving. egui-macview avoids this automatically:

• Spring animations (CASpring) request repaints only while a transition is in flight. As soon as a toggle switch, segmented pill, or disclosure chevron settles at its target position, it stops requesting repaints (0% CPU at rest).
• Floating media HUD (MacPlayerView) schedules a single wakeup timer (request_repaint_after_secs) for its 3.0-second auto-hide instead of polling every frame.
• Unfocused & minimized windows: Continuous animations (such as indeterminate progress spinners) check is_window_active(ctx) and ui.is_rect_visible(rect) and pause automatically when your app window is in the background or minimized.

Quality & Testing

Run the full test suite and linter with:

cargo test --all-targets
cargo test --doc
cargo clippy --all-targets -- -D warnings

• 28 integration test suites and 65+ documentation tests verify widget layout, keyboard navigation, undo/redo roundtrips, WCAG contrast ratios, and zero idle CPU usage.
• Design token architecture: All dimensions, spacing, corner radii, and semantic colors live in tokens/design_tokens.json ([MacDesignTokens]) and are resolved through [MacTheme].

License, Third-Party Notices & Trademark Disclaimer

Software License & Warranty Disclaimer

egui-macview is dual-licensed under either of:

• MIT License (https://opensource.org/licenses/MIT, see LICENSE)
• Apache License, Version 2.0 (https://www.apache.org/licenses/LICENSE-2.0)

at your option. The software is provided "AS IS", without warranty or liability of any kind, express or implied.

Open-Source Font & Asset Notices

All bundled fonts and vector assets in egui-macview are 100% open-source:

• Inter (assets/fonts/Inter-Regular.ttf, assets/fonts/Inter-SemiBold.ttf): Copyright (c) 2016 The Inter Project Authors, licensed under the SIL Open Font License 1.1 (assets/fonts/Inter-OFL.txt).
• CupertinoIcons (assets/fonts/CupertinoIcons.ttf): Copyright 2014 The Flutter Authors, licensed under the MIT License (assets/fonts/CupertinoIcons-LICENSE.txt).

Zero proprietary Apple fonts, icons, bitmaps, or binaries are included or distributed with this crate.

Trademark & Clean-Room Non-Affiliation Disclaimer

Apple®, macOS®, AppKit®, Aqua®, Finder®, QuickTime®, AVKit®, and SF Pro® are trademarks of Apple Inc., registered in the U.S. and other countries. egui-macview is an independent, clean-room open-source UI library for egui and is not affiliated with, endorsed by, or sponsored by Apple Inc. All references to macOS, AppKit, or AVKit class and style names are used solely for nominative, descriptive interoperability and developer familiarity.