Positioner

GitHub npm crates.io

API Reference

Position your windows at well-known locations.

This plugin is a port of electron-positioner for Tauri.

Supported Platforms

• Windows
• Linux
• macOS

Setup

This plugin requires a Rust version of at least 1.75

Install the positioner plugin to get started.

Note

If you only intend on moving the window from Rust code, you only need the dependency in src-tauri/Cargo.toml, and can remove the plugin registration from lib.rs if you choose to setup automatically.

Automatic

Use your project’s package manager to add the dependency:

npm

npm run tauri add positioner

Yarn

yarn run tauri add positioner

pnpm

pnpm tauri add positioner

Cargo

cargo tauri add positioner

Manual

1. Install the positioner plugin by adding the following to your Cargo.toml file:

   src-tauri/Cargo.toml

   [dependencies]
   tauri-plugin-positioner = "2.0.0-beta"
   # alternatively with Git:
   tauri-plugin-positioner = { git = "https://github.com/tauri-apps/plugins-workspace", branch = "v2" }

2. Modify lib.rs to initialize the plugin:

   src-tauri/src/lib.rs

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

3. Install the JavaScript Guest bindings using your preferred JavaScript package manager:

   npm

   npm install @tauri-apps/plugin-positioner

   Yarn

   yarn add @tauri-apps/plugin-positioner

   pnpm

   pnpm add @tauri-apps/plugin-positioner

Additional setup is required to get tray-relative positions to work.

1. Add tray-icon feature to your Cargo.toml file:

   src-tauri/Cargo.toml

   [dependencies]
   tauri-plugin-positioner = { version = "2.0.0-beta", features = ["tray-icon"] }

2. Setup on_tray_event for positioner plugin:

   src-tauri/src/lib.rs

   fn run() {
     tauri::Builder::default()
       .plugin(tauri_plugin_positioner::init())
       // This is required to get tray-relative positions to work
       .setup(|app| {
         TrayIconBuilder::new()
           .on_tray_icon_event(|app, event| {
             tauri_plugin_positioner::on_tray_event(app.app_handle(), &event);
           })
           .build(app)?;
         Ok(())
       })
       .run(tauri::generate_context!())
       .expect("error while running tauri application");
   }

Usage

The plugin’s APIs are available through the JavaScript guest bindings:

import { moveWindow, Position } from '@tauri-apps/plugin-positioner';

moveWindow(Position.TopRight);

You can import and use the Window trait extension directly through Rust:

use tauri_plugin_positioner::{WindowExt, Position};

let mut win = app.get_webview_window("main").unwrap();
let _ = win.as_ref().window().move_window(Position::TopRight);

Permissions

By default all plugin commands are blocked and cannot be accessed. You must define a list of permissions in your capabilities configuration.

See Access Control List for more information.

src-tauri/capabilities/main.json

{
  "permissions": [
    ...,
    "positioner:default",
  ]
}

Permission	Description
positioner:allow-move-window	Enables the move_window command without any pre-configured scope.
positioner:deny-move-window	Denies the move_window command without any pre-configured scope.
positioner:default	Allows the move_window command.