🚀 Ship Your App Faster: Try Fastforge - The simplest way to build, package and distribute your Flutter apps.

This plugin allows Flutter desktop apps to defines system/inapp wide hotkey (i.e. shortcut).

English | 简体中文

• hotkey_manager
  • Platform Support
  • Quick Start
    • Installation
      • Linux requirements
    • Usage
  • Who's using it?
  • API
    • HotKeyManager
  • Related Links
  • License

System shortcuts use the C++ nativeapi core through Dart FFI. No per-platform native hotkey_manager plugin or method channel is needed.

Requires Dart 3.13+, Flutter 3.47+ and nativeapi/cnativeapi 0.5.4+ with native keycode support. Both dependencies are published on pub.dev; no local dependency overrides are needed.

import 'package:hotkey_manager/native.dart' as hotkey;

final manager = hotkey.ShortcutManager.instance;
final listenerId = manager.addListener((event) {
  if (event is hotkey.ShortcutActivatedEvent) {
    print('Pressed: ${event.accelerator}');
  } else if (event is hotkey.ShortcutReleasedEvent) {
    print('Released: ${event.accelerator}'); // macOS
  }
});
final shortcut = manager.registerWithOptions(const hotkey.ShortcutOptions(
  accelerator: 'Ctrl+Alt+Q',
  description: 'Quick action',
  scope: hotkey.ShortcutScope.global,
  enabled: true,
));
if (shortcut == null) {
  throw StateError('Shortcut unavailable or unsupported');
}

// When the registration is no longer needed:
manager.unregisterWithId(shortcut.id);
shortcut.dispose();
manager.removeListener(listenerId);

Use addListener for Flutter callbacks: events are delivered asynchronously to the registering Dart isolate. A shortcut handle must be unregistered before it is disposed; disposing the handle alone does not remove the native registration.

The existing HotKeyManager, HotKey, HotKeyRecorder, HotKeyVirtualView, GlobalShortcuts and CallbackGlobalShortcuts remain available from the original package:hotkey_manager/hotkey_manager.dart import, and from package:hotkey_manager/legacy.dart. Old hotkey JSON is supported. In-app shortcuts continue to use Flutter's HardwareKeyboard, with down and up events on all Flutter platforms. System key-up events are available on macOS; Windows and Linux report system key-down only. Fn is supported on macOS; CapsLock is supported on macOS and Linux. Windows retains the old behavior of ignoring Fn/CapsLock, and Linux ignores Fn. Unmapped system keys throw PlatformException. The original platform keycodes preserve media, international and keypad keys, and Windows system shortcuts retain native automatic repetition. Linux system shortcuts require X11 (including XWayland), not native Wayland.

The original injectable HotKeyManagerPlatform and MethodChannelHotKeyManager interfaces are retained; the default implementation uses nativeapi. The native shortcut types are exported separately from package:hotkey_manager/native.dart to avoid collisions with Flutter’s ShortcutManager.

Repeated registration of the same identifier retains any omitted handlers. registeredHotKeyList remains a live list. Different identifiers with the same combination share one native registration and each receive events. hotKeyManager.unregisterAll() clears this package's shortcuts, including leftovers after a hot restart, while preserving shortcuts registered directly through ShortcutManager.

In-app hotkeys observe Flutter key events without consuming text input. Filter a callback using the relevant FocusNode.hasFocus when it should be inactive while typing. Use Flutter Shortcuts/Actions for shortcuts that should consume events or follow focused-widget priority. Modifier-only in-app hotkeys are supported; use PhysicalKeyboardKey.shiftLeft and PhysicalKeyboardKey.shiftRight for independent bindings. Entries in HotKey.modifiers intentionally match either side; a handler can inspect HardwareKeyboard.instance.physicalKeysPressed if it needs to distinguish the side of a modifier in a chord.

HotKeyScope.system works regardless of which application is focused. To reserve a shortcut only in the background, register it when your application becomes inactive/hidden and unregister it when it becomes active/visible again. This is an application lifecycle policy rather than another hotkey scope.

Always await registration and handle PlatformException: reserved or already owned combinations fail without replacing another application's shortcut. Unmodified keys such as Space are subject to the operating system's rules. macOS keys without a native keycode, including the media Play/Pause key, fail with unsupported_hotkey instead of terminating the process. That error does not claim support for delivery of those media keys. System-reserved combinations (such as the task switcher or Spotlight) must first be disabled or reassigned in the operating system; this package does not override those reservations.

Use the Git dependency for the nativeapi migration described here:

dependencies:
  hotkey_manager:
    git:
      path: packages/hotkey_manager
      url: https://github.com/leanflutter/hotkey_manager.git
      ref: main

sudo apt-get install clang cmake ninja-build pkg-config libgtk-3-dev libx11-dev libxi-dev

import 'package:hotkey_manager/hotkey_manager.dart';

void main() async {
  // Must add this line.
  WidgetsFlutterBinding.ensureInitialized();
  // Reclaim native registrations left over after a hot restart.
  await hotKeyManager.unregisterAll();

  runApp(MyApp());
}

Register/Unregsiter a system/inapp wide hotkey.

// ⌥ + Q
HotKey _hotKey = HotKey(
  key: PhysicalKeyboardKey.keyQ,
  modifiers: [HotKeyModifier.alt],
  // Set hotkey scope (default is HotKeyScope.system)
  scope: HotKeyScope.inapp, // Set as inapp-wide hotkey.
);
await hotKeyManager.register(
  _hotKey,
  keyDownHandler: (hotKey) {
    print('onKeyDown+${hotKey.toJson()}');
  },
  // System key-up is macOS only; in-app key-up works on all platforms.
  keyUpHandler: (hotKey){
    print('onKeyUp+${hotKey.toJson()}');
  } ,
);

await hotKeyManager.unregister(_hotKey);

await hotKeyManager.unregisterAll();

Use HotKeyRecorder widget to help you record a hotkey.

HotKeyRecorder(
  onHotKeyRecorded: (hotKey) {
    _hotKey = hotKey;
    setState(() {});
  },
),

Please see the example app of this plugin for a full example.

• Airclap - Send any file to any device. cross platform, ultra fast and easy to use.
• AuthPass - Password Manager based on Flutter for all platforms. Keepass 2.x (kdbx 3.x) compatible.
• Biyi (比译) - A convenient translation and dictionary app.

• nativeapi
• nativeapi C++ core

MIT