tauri-nspanel

Create macOS panels for your Tauri app. Convert a regular window into a panel, or configure a new window with the panel builder.

Note: For the previous version, see the v2 branch.

What are panels?

Panels are a special type of window on macOS (NSPanel) that float above other windows and provide auxiliary controls or information. They're commonly used for tool palettes, inspectors, floating controls, and HUD displays.

Quick Start

1. Installation

[dependencies]
tauri-nspanel = { git = "https://github.com/ahkohd/tauri-nspanel", branch = "v2.1" }

fn main() {
    tauri::Builder::default()
        .plugin(tauri_nspanel::init())
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

2. Define and Create a Panel

use tauri_nspanel::{tauri_panel, PanelBuilder, PanelLevel, WebviewUrl};

// Define panel class
tauri_panel! {
    panel!(MyPanel {
        config: {
            canBecomeKeyWindow: true,
            isFloatingPanel: true
        }
    })
}

// Create panel with builder
let panel = PanelBuilder::<_, MyPanel>::new(app.handle(), "my-panel")
    .url(WebviewUrl::App("panel.html".into()))
    .level(PanelLevel::Floating)
    .build()?;

panel.show();

3. Access from Commands

use tauri_nspanel::ManagerExt;

#[tauri::command]
fn show_panel(app: tauri::AppHandle) {
    if let Ok(panel) = app.get_webview_panel("my-panel") {
        panel.show_and_make_key();
    }
}

#[tauri::command]
fn close_panel(app_handle: tauri::AppHandle) {
    app_handle
        .get_webview_panel("my-panel")
        .ok()
        .and_then(|panel| panel.to_window())
        .map(|window| window.close());
}

Documentation

Complete Documentation

• Installation - Setup and requirements
• Getting Started - Quick start guide
• Panel Classes - Define custom panel behavior
• PanelBuilder API - Build panels with fluent API
• Event Handling - Handle panel events and mouse tracking
• Panel Methods - Control panel behavior and appearance
• Key Types - PanelLevel, StyleMask, CollectionBehavior, etc.
• Thread Safety - Understanding thread-safe panel operations
• Examples - Working examples and patterns

Features

• Create panels with PanelBuilder API or convert existing windows
• Corner radius, transparency, shadows, and more styling options
• Mouse tracking with enter, exit, and move events
• Type-safe NSWindowDelegate callbacks
• Window levels, collection behavior, and style masks
• Works with existing Tauri windows and commands
• Thread-safe operations handled on main thread

Examples

Check out the examples directory:

Core Examples (Rust)

• panel_macro.rs - Basic panel creation
• panel_builder.rs - PanelBuilder API usage
• panel_event_macro.rs - Event handling

Complete Applications

• basic/ - Basic setup with vanilla JS
• panel_builder/ - Advanced builder configuration
• mouse_tracking/ - Mouse events and tracking
• hover_activate/ - Auto-activate on hover

Run examples:

# Rust examples
cargo run --example panel_builder

# Full applications
cd examples/basic && pnpm install && pnpm tauri dev

Showcase

Some projects using tauri-nspanel:

• Cap - Screen recording
• Screenpipe - AI screen recording
• EcoPaste - Clipboard manager
• Hyprnote - Note-taking
• BongoCat - Desktop pet
• Coco - AI Search and Assistant
• Overlayed - Screen overlay
• Verve - Launcher
• JET Pilot - Kubernetes manager
• Buffer - AI-powered Markdown note app

Contributing

PRs accepted. Please read the Contributing Guide before making a pull request.

License

MIT or MIT/Apache 2.0 where applicable.