Struct PanelBuilder

pub struct PanelBuilder<'a, R: Runtime, T: FromWindow<R> + 'static> { /* private fields */ }

Builder for creating panels with Tauri-like API

PanelBuilder provides a fluent interface that creates a Tauri window, converts it to an NSPanel, and applies panel-specific configurations. It can work with both the default panel type or custom panel classes created with the panel! macro.

Type Parameters

• R: The Tauri runtime type
• T: The panel type (must implement FromWindow<R>)

Example

use tauri_nspanel::{panel, PanelBuilder, PanelLevel};

// Using default panel type
let panel = PanelBuilder::new(&app, "my-panel")
    .url(WebviewUrl::App("panel.html".into()))
    .title("Tool Panel")
    .level(PanelLevel::Floating)
    .build()?;

// Using custom panel type
panel!(CustomPanel {
    config: {
        can_become_key_window: false
    }
});

let custom = PanelBuilder::<_, CustomPanel>::new(&app, "custom")
    .url(WebviewUrl::App("custom.html".into()))
    .build()?;

Implementations

impl<'a, R: Runtime + 'a, T: FromWindow<R> + 'static> PanelBuilder<'a, R, T>

pub fn new(handle: &'a AppHandle<R>, label: impl Into<String>) -> Self

Create a new PanelBuilder

pub fn url(self, url: WebviewUrl) -> Self

Set the webview URL

pub fn title(self, title: impl Into<String>) -> Self

Set the window title

pub fn position(self, position: Position) -> Self

Set the window position

pub fn size(self, size: Size) -> Self

Set the window size

pub fn floating(self, floating: bool) -> Self

Set whether the panel floats above other windows

pub fn level(self, level: PanelLevel) -> Self

Set the window level

The window level determines the panel’s position in the window hierarchy. Higher levels appear above lower levels.

Example

use tauri_nspanel::{PanelBuilder, PanelLevel};
// Create a panel that floats above normal windows
PanelBuilder::new(&app, "floating")
    .level(PanelLevel::Floating)
    .build();

// Create a status-level panel (appears above floating panels)
PanelBuilder::new(&app, "status")
    .level(PanelLevel::Status)
    .build();

pub fn has_shadow(self, has_shadow: bool) -> Self

Set whether the panel has a shadow

pub fn opaque(self, opaque: bool) -> Self

Set whether the panel is opaque

pub fn alpha_value(self, alpha: f64) -> Self

Set the alpha value (transparency)

pub fn hides_on_deactivate(self, hides: bool) -> Self

Set whether the panel hides when the app is deactivated

pub fn becomes_key_only_if_needed(self, value: bool) -> Self

Set whether the panel becomes key window only if needed

pub fn accepts_mouse_moved_events(self, value: bool) -> Self

Set whether the panel accepts mouse moved events

pub fn ignores_mouse_events(self, value: bool) -> Self

Set whether the panel ignores mouse events

pub fn movable_by_window_background(self, value: bool) -> Self

Set whether the panel is movable by its background

pub fn released_when_closed(self, value: bool) -> Self

Set whether the panel is released when closed

pub fn works_when_modal(self, value: bool) -> Self

Set whether the panel works when modal dialogs are displayed

pub fn content_size(self, size: Size) -> Self

Set the content size (inner size excluding window decorations)

pub fn style_mask(self, style_mask: StyleMask) -> Self

Set the window style mask

Style masks control the appearance and behavior of the window frame.

Example

use tauri_nspanel::{PanelBuilder, StyleMask};
// Create a borderless panel
PanelBuilder::new(&app, "borderless")
    .style_mask(StyleMask::empty().borderless())
    .build();

// Create a HUD-style panel
PanelBuilder::new(&app, "hud")
    .style_mask(
        StyleMask::empty()
            .hud_window()
            .titled()
            .closable()
    )
    .build();

pub fn collection_behavior(self, behavior: CollectionBehavior) -> Self

Set the collection behavior

Collection behaviors control how the panel participates in Spaces, Exposé, and fullscreen mode on macOS.

Example

use tauri_nspanel::{CollectionBehavior, PanelBuilder};
// Create a panel that appears on all spaces and doesn't participate in cycling
PanelBuilder::new(&app, "tool-panel")
    .collection_behavior(
        CollectionBehavior::new()
            .can_join_all_spaces()
            .ignores_cycle()
    )
    .build();

pub fn no_activate(self, no_activate: bool) -> Self

Prevent focus stealing during window creation

Since PanelBuilder creates a regular window before converting it to a panel, the window creation phase can steal focus. When set to true, the application’s activation policy is temporarily set to Prohibited during window creation, preventing this focus interruption.

This works particularly well with apps that use ActivationPolicy::Accessory, ensuring the window is created silently before being converted to a panel.

Example

use tauri_nspanel::{PanelBuilder, PanelLevel};
use tauri::WebviewUrl;
// Create a utility panel that doesn't steal focus
PanelBuilder::new(&app, "utility")
    .url(WebviewUrl::App("utility.html".into()))
    .no_activate(true)
    .level(PanelLevel::Floating)
    .build();

pub fn corner_radius(self, radius: f64) -> Self

Set the corner radius for rounded corners

This enables the layer-backed view and sets the corner radius on the panel’s layer, giving the panel rounded corners with the specified radius.

Example

use tauri_nspanel::PanelBuilder;
use tauri::WebviewUrl;
PanelBuilder::new(&app, "rounded-panel")
    .url(WebviewUrl::App("index.html".into()))
    .corner_radius(10.0)  // 10pt corner radius
    .build();

pub fn transparent(self, transparent: bool) -> Self

Set the panel background to be transparent

This sets the window background color to clear and makes the panel non-opaque, allowing content behind the panel to show through.

Example

use tauri_nspanel::PanelBuilder;
use tauri::WebviewUrl;
PanelBuilder::new(&app, "transparent-panel")
    .url(WebviewUrl::App("index.html".into()))
    .transparent(true)  // Transparent background
    .build();

pub fn with_window<F>(self, f: F) -> Self

where F: FnOnce(WebviewWindowBuilder<'a, R, AppHandle<R>>) -> WebviewWindowBuilder<'a, R, AppHandle<R>> + 'static,

Apply a custom configuration function to the WebviewWindowBuilder

This allows access to any Tauri window configuration not exposed by the panel builder. The closure receives the WebviewWindowBuilder and should return it after applying any desired configurations.

Example

use tauri_nspanel::PanelBuilder;
use tauri::WebviewUrl;
PanelBuilder::new(&app, "my-panel")
    .url(WebviewUrl::App("index.html".into()))
    .with_window(|window| {
        window
            .min_inner_size(300.0, 200.0)
            .max_inner_size(800.0, 600.0)
            .resizable(false)
            .decorations(false)
            .always_on_top(true)
            .skip_taskbar(true)
    })
    .build()

pub fn build(self) -> Result<Arc<dyn Panel<R>>>

Build the panel

Creates a Tauri window using the configured properties, converts it to an NSPanel, and applies all panel-specific settings.