This package lets you add support for user-customizable global keyboard shortcuts to your macOS app in minutes. It's fully sandbox and Mac App Store compatible. And it's used in production by Dato, Jiffy, Plash, and Lungo.
I'm happy to accept more configurability and features. PR welcome! What you see here is just what I needed for my own apps.
Requirements
macOS 10.11+
Install
Swift Package Manager
Add https://github.com/sindresorhus/KeyboardShortcuts
in the “Swift Package Manager” tab in Xcode.
You also need to set the build setting “Other Linker Flags” to -weak_framework Combine
to work around this Xcode bug.
Carthage
github "sindresorhus/KeyboardShortcuts"
CocoaPods
pod 'KeyboardShortcuts'
Usage
First, register a name for the keyboard shortcut.
Constants.swift
import KeyboardShortcuts
extension KeyboardShortcuts.Name {
static let toggleUnicornMode = Self("toggleUnicornMode")
}
You can then refer to this strongly-typed name in other places.
You will want to make a view where the user can choose a keyboard shortcut.
PreferencesView.swift
import SwiftUI
import KeyboardShortcuts
struct PreferencesView: View {
var body: some View {
HStack {
Text("Toggle Unicorn Mode:")
KeyboardShortcuts.Recorder(for: .toggleUnicornMode)
}
}
}
There's also support for Cocoa instead of SwiftUI.
KeyboardShortcuts.Recorder
takes care of storing the keyboard shortcut in UserDefaults
and also warning the user if the chosen keyboard shortcut is already used by the system or the app's main menu.
Add a listener for when the user presses their chosen keyboard shortcut.
AppDelegate.swift
import Cocoa
import KeyboardShortcuts
@main
final class AppDelegate: NSObject, NSApplicationDelegate {
func applicationDidFinishLaunching(_ notification: Notification) {
KeyboardShortcuts.onKeyUp(for: .toggleUnicornMode) { [self] in
// The user pressed the keyboard shortcut for “unicorn mode”!
isUnicornMode.toggle()
}
}
}
You can also listen to key down with .onKeyDown()
That's all!
You can find a complete example by opening KeyboardShortcuts.xcodeproj
and then running the KeyboardShortcutsExample
target.
You can also find a real-world example in my Plash app.
Cocoa
Use KeyboardShortcuts.RecorderCocoa
instead of KeyboardShortcuts.Recorder
.
import Cocoa
import KeyboardShortcuts
final class PreferencesViewController: NSViewController {
override func loadView() {
view = NSView()
let recorder = KeyboardShortcuts.RecorderCocoa(for: .toggleUnicornMode)
view.addSubview(recorder)
}
}
API
Tips
NSMenuItem
Show a recorded keyboard shortcut in an
Dynamic keyboard shortcuts
Your app might need to support keyboard shortcuts for user-defined actions. Normally, you would statically register the keyboard shortcuts upfront in extension KeyboardShortcuts.Name {}
. However, this is not a requirement. It's only for convenience so that you can use dot-syntax when calling various APIs (for example, .onKeyDown(.unicornMode) {}
). You can create KeyboardShortcut.Name
's dynamically and store them yourself. You can see this in action in the example project.
Default keyboard shortcuts
Setting a default keyboard shortcut can be useful if you're migrating from a different package or just making something for yourself. However, please do not set this for a publicly distributed app. Users find it annoying when random apps steal their existing keyboard shortcuts. It’s generally better to show a welcome screen on the first app launch that lets the user set the shortcut.
import KeyboardShortcuts
extension KeyboardShortcuts.Name {
static let toggleUnicornMode = Self("toggleUnicornMode", default: .init(.k, modifiers: [.command, .option]))
}
FAQ
MASShortcut
?
How is it different from This package:
- Written in Swift with a swifty API.
- More native-looking UI component.
- SwiftUI component included.
- Support for listening to key down, not just key up.
- Swift Package Manager support.
- Connect a shortcut to an
NSMenuItem
.
MASShortcut
:
- More mature.
- More features.
- Localized.
HotKey
?
How is it different from HotKey
is good for adding hard-coded keyboard shortcuts, but it doesn't provide any UI component for the user to choose their own keyboard shortcuts.
Carbon
? Isn't that deprecated?
Why is this package importing Most of the Carbon APIs were deprecated years ago, but there are some left that Apple never shipped modern replacements for. This includes registering global keyboard shortcuts. However, you should not need to worry about this. Apple will for sure ship new APIs before deprecating the Carbon APIs used here.
Does this package cause any permission dialogs?
No.
How can I add an app-specific keyboard shortcut that is only active when the app is?
That is outside the scope of this package. You can either use NSEvent.addLocalMonitorForEvents
, NSMenuItem
with keyboard shortcut (it can even be hidden), or SwiftUI's View#keyboardShortcut()
modifier.
Related
- Preferences - Add a preferences window to your macOS app in minutes
- LaunchAtLogin - Add "Launch at Login" functionality to your macOS app
- Defaults - Swifty and modern UserDefaults
- More…