vercel-labs / vercel-labs/native

feat: global keyboard shortcut / hotkey support

Open
#45 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Zig
Stars
7.7k
Forks
314
Avg merge
5h
Merged PRs (30d)
13

Description

Feature request

Global keyboard shortcuts — the ability to register system-wide hotkeys that trigger actions regardless of which app has focus.

Why this matters

This is table-stakes for many desktop app categories. Without it, zero-native apps are stuck as "browser tabs in a window frame" — they can only respond when the user tabs into them.

Real-world use cases

1. Gaming overlays (the one that made me notice this)

A League of Legends desktop assistant needs Shift+Tab to toggle an overlay showing live match data, champion stats, and post-game analysis — all while the user is in-game without alt-tabbing:

// What we do in Tauri today:
tauri_plugin_global_shortcut::Builder::new()
    .with_shortcut("Shift+Tab")
    .with_handler(|app, _shortcut, event| {
        // toggle overlay window visibility
    })
    .build()

2. Screenshot / clipboard tools
Ctrl+Shift+4 to capture a region, Ctrl+Shift+V to paste from history.

3. Quick launchers / search bars
Alt+Space to pop up an Alfred/PowerToys-style launcher.

4. Media / productivity apps
Play/pause, next track, mute mic — things users expect to work while typing in another app.

5. AI copilots / assistants
Ctrl+Shift+A to summon a floating chat window from anywhere.

What exists today (v0.2.0)

Scanned the codebase:

  • TrayOptions / TrayItemId structs are declared in src/platform/root.zig but have zero implementation in any platform backend
  • No global_shortcut or hotkey anywhere in src/, tools/, or skill-data/
  • tauri-plugin-global-shortcut does not exist in the zero-native ecosystem
What makes this particularly important for zero-native

zero-native is targeting the Tauri replacement space. The top Tauri plugin by download count is tauri-plugin-global-shortcut. Every serious Tauri→zero-native migration hits this wall immediately.

The security model is actually a selling point here — shortcuts should be opt-in and policy-controlled just like the bridge, navigation, and everything else in app.zon:

.shortcuts = .{
    .{ .key = "Shift+Tab", .command = "toggle-overlay", .permissions = .{"window"} },
    .{ .key = "Ctrl+Shift+Space", .command = "quick-search" },
}
Platform APIs available
Platform API
Windows RegisterHotKey / UnregisterHotKey (Win32)
macOS NSEvent.addGlobalMonitorForEventsMatchingMask or Carbon RegisterEventHotKey
Linux (X11) XGrabKey
Linux (Wayland) zwp_keyboard_shortcuts_inhibit_manager_v1 (protocol-dependent, may need portal)
Suggested scope
  1. app.zon schema — a shortcuts array with key, command label, and optional permissions
  2. Platform backendregister_hotkey / unregister_hotkey in the Platform vtable
  3. Bridge integration — shortcut fires a window.zero event or invokes a registered bridge command
  4. Platform support — start with Windows (RegisterHotKey is trivial) + macOS, Linux as follow-up

Happy to elaborate on any of these or help test — I have a real app waiting to migrate 😄

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the TrayOptions and TrayItemId declarations in src/platform/root.zig, then trace the Platform vtable and app.zon configuration model. Compare the Windows and macOS platform API requirements before deciding how registration reaches the bridge. Done means the schema, platform registration path, and shortcut-triggered window.zero event or bridge command are defined for the proposed platforms.

Written by the indexing model from the issue text.

Assessment

Tech stack
zig
Domain
desktop, operating-systems
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.