Skip to main content
NativePHP Desktop allows you to register global keyboard shortcuts that work even when your application is not focused.

​
Registering Shortcuts

​
Basic Registration

Register a global shortcut that triggers an event: 
use Native\Desktop\Facades\GlobalShortcut;

GlobalShortcut::key('CommandOrControl+Shift+K')
    ->event('shortcuts.quick-capture')
    ->register();

​
Shortcut Syntax

Use the following modifiers in your key combinations:
  • CommandOrControl - Command on macOS, Control on Windows/Linux
  • Command or Cmd - macOS only
  • Control or Ctrl - Control key
  • Alt or Option - Alt key
  • Shift - Shift key
  • Super - Windows key on Windows/Linux
Example key combinations: 
// Cross-platform shortcuts
GlobalShortcut::key('CommandOrControl+Q')->event('app.quit')->register();
GlobalShortcut::key('CommandOrControl+N')->event('window.new')->register();
GlobalShortcut::key('CommandOrControl+Shift+P')->event('command.palette')->register();

// Function keys
GlobalShortcut::key('F12')->event('devtools.toggle')->register();

// Letter keys
GlobalShortcut::key('CommandOrControl+K')->event('search.focus')->register();
Use CommandOrControl instead of Command or Control to ensure your shortcuts work across all platforms.

​
Handling Shortcut Events

Listen for the events triggered by your shortcuts: 
use Native\Desktop\Events\GlobalShortcut\GlobalShortcutPressed;

Event::listen(function (GlobalShortcutPressed $event) {
    if ($event->event === 'shortcuts.quick-capture') {
        // Handle quick capture shortcut
        app(CaptureService::class)->startCapture();
    }
});
Or use dedicated event listeners: 
namespace App\Listeners;

use Native\Desktop\Events\GlobalShortcut\GlobalShortcutPressed;

class HandleQuickCapture
{
    public function handle(GlobalShortcutPressed $event)
    {
        if ($event->event === 'shortcuts.quick-capture') {
            // Bring window to front
            Window::current()->show();
            
            // Focus capture input
            Window::current()->focus();
        }
    }
}

​
Unregistering Shortcuts

Remove a registered global shortcut: 
GlobalShortcut::key('CommandOrControl+Shift+K')
    ->unregister();

​
Common Use Cases

use Native\Desktop\Facades\GlobalShortcut;
use Native\Desktop\Facades\Window;

class ShortcutServiceProvider extends ServiceProvider
{
    public function boot()
    {
        // Register quick capture shortcut
        GlobalShortcut::key('CommandOrControl+Shift+Space')
            ->event('capture.quick')
            ->register();

        Event::listen(function (GlobalShortcutPressed $event) {
            if ($event->event === 'capture.quick') {
                Window::current()->show();
                Window::current()->focus();
            }
        });
    }
}

​
Best Practices

1
Choose Unique Combinations
2
Avoid common shortcuts that might conflict with other applications. Use modifier combinations like CommandOrControl+Shift+Key to reduce conflicts.
3
Provide Configuration
4
Allow users to customize shortcuts in your application settings, as different users may have different preferences or conflicts.
5
Document Your Shortcuts
6
Make your global shortcuts discoverable by listing them in your application’s help menu or settings panel.
7
Clean Up on Exit
8
Unregister shortcuts when your application closes or when users disable features that use them.

​
Platform Differences

Be aware of platform-specific behaviors:
  • macOS: Some shortcuts may be reserved by the system
  • Windows: Windows key combinations may conflict with system shortcuts
  • Linux: Behavior may vary depending on the desktop environment
Global shortcuts can conflict with system shortcuts or other applications. Always use modifier combinations and provide a way for users to customize or disable shortcuts.
If a shortcut is already registered by another application, the registration will fail silently. Consider providing feedback to users if critical shortcuts cannot be registered.

Build docs developers (and LLMs) love

Get started for freeTalk to us