This package lets you add support for user-customizable global keyboard shortcuts to your macOS app in minutes. It's fully sandboxed and Mac App Store compatible.

This fork focuses on a native-styled recorder UI and app-settings table behavior while keeping the core keyboard-shortcut APIs compatible with upstream usage.

macOS 14+

Add https://github.com/Ailogeneous/KeyboardShortcutsNative in the “Swift Package Manager” tab in Xcode.

For a full, fork-aligned implementation, see: https://github.com/Ailogeneous/KeyboardShortcutsNative/blob/main/Example/KeyboardShortcutsExample/MainScreen.swift

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.

SettingsScreen.swift

import SwiftUI
import KeyboardShortcuts

struct SettingsScreen: View {
	@State private var selectedField: KeyboardShortcuts.Name?

	var body: some View {
		VStack(spacing: 0) {
			KeyboardShortcutRecorder(
				for: .toggleUnicornMode,
				label: "Toggle Unicorn Mode",
				focused: $selectedField
			)
		}
	}
}

KeyboardShortcutRecorder stores the shortcut in UserDefaults and warns when the chosen shortcut conflicts with the system or app menu.

Add a listener for when the user presses their chosen keyboard shortcut.

App.swift

import SwiftUI
import KeyboardShortcuts

@main
struct YourApp: App {
	@State private var appState = AppState()

	var body: some Scene {
		WindowGroup {
			// …
		}
		Settings {
			SettingsScreen()
		}
	}
}

final class AppState {
	init() {
		KeyboardShortcuts.onKeyUp(for: .toggleUnicornMode) {
			print("toggleUnicornMode released")
		}
	}
}

You can also listen for key-down with KeyboardShortcuts.onKeyDown(for:action:).

That's all.

For a complete, fork-aligned implementation, use the example app in this repository: Example/KeyboardShortcutsExample.

This fork currently provides the SwiftUI KeyboardShortcutRecorder API only.

This package supports localizations. PRs welcome for more!

1. Fork the repo.
2. Create a directory that has a name that uses an ISO 639-1 language code and optional designators, followed by the .lproj suffix. More here.
3. Create a file named Localizable.strings under the new language directory and then copy the contents of Sources/KeyboardShortcuts/Localization/en.lproj/Localizable.strings into it.
4. Localize and make sure to review your localization multiple times. Check for typos.
5. Try to find someone that speaks your language to review the translation.
6. Submit a PR.

The API surface stays close to upstream KeyboardShortcuts, with fork-specific recorder UI behavior.

Most-used APIs:

• KeyboardShortcutRecorder(for:label:focused:onInteraction:onChange:)
• KeyboardShortcuts.onKeyDown(for:action:) / KeyboardShortcuts.onKeyUp(for:action:)
• KeyboardShortcuts.events(for:) and KeyboardShortcuts.events(_:for:)
• KeyboardShortcuts.getShortcut(for:) / KeyboardShortcuts.setShortcut(_:for:)
• KeyboardShortcuts.reset(_:) / KeyboardShortcuts.resetAll()
• KeyboardShortcuts.enable(_:) / KeyboardShortcuts.disable(_:) / KeyboardShortcuts.isEnabled(for:)

Note: Hosted API docs on Swift Package Index currently point to upstream and may not reflect fork-specific UI behavior exactly.

This fork does not include upstream's NSMenuItem helper extension, but you can wire it directly:

if let shortcut = KeyboardShortcuts.getShortcut(for: .toggleUnicornMode) {
	var modifierMask = NSEvent.ModifierFlags()
	if shortcut.modifiers.contains(.command) { modifierMask.insert(.command) }
	if shortcut.modifiers.contains(.option) { modifierMask.insert(.option) }
	if shortcut.modifiers.contains(.shift) { modifierMask.insert(.shift) }
	if shortcut.modifiers.contains(.control) { modifierMask.insert(.control) }

	menuItem.keyEquivalent = shortcut.nsMenuItemKeyEquivalent ?? ""
	menuItem.keyEquivalentModifierMask = modifierMask
} else {
	menuItem.keyEquivalent = ""
	menuItem.keyEquivalentModifierMask = []
}

Your app might need keyboard shortcuts for user-defined actions. Normally, you statically register names in extension KeyboardShortcuts.Name {}. That is optional and mainly for dot-syntax convenience when calling APIs (for example, KeyboardShortcuts.onKeyDown(for: .unicornMode) {}). You can also create KeyboardShortcuts.Name values dynamically and store them yourself.

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]))
}

To get all keyboard shortcut names, conform KeyboardShortcuts.Name to CaseIterable.

import KeyboardShortcuts

extension KeyboardShortcuts.Name {
	static let foo = Self("foo")
	static let bar = Self("bar")
}

extension KeyboardShortcuts.Name: CaseIterable {
	public static let allCases: [Self] = [
		.foo,
		.bar
	]
}

// …

print(KeyboardShortcuts.Name.allCases)

And to get all names with a configured shortcut:

print(KeyboardShortcuts.Name.allCases.filter { $0.shortcut != nil })

You can get a symbolic representation of modifier flags like this:

import KeyboardShortcuts

let modifiers = NSEvent.ModifierFlags([.command, .shift])
print(modifiers.ks_symbolicRepresentation)
//=> "⇧⌘"

// Also works with shortcuts:
if let shortcut = KeyboardShortcuts.getShortcut(for: .toggleUnicornMode) {
	print(shortcut.modifiers.description)
	//=> "⌘⌥"
}

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.
• Works when NSMenu is open (e.g. menu bar apps).

MASShortcut:

• More mature.
• More localizations.

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.

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.

No.

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.

No, since it would not work for sandboxed apps. If your app is not sandboxed, you can use MediaKeyTap.

No, Caps Lock is a modifier key and cannot be directly listened to using this package's standard event methods. If you need to detect Caps Lock events, you'll need to use lower-level APIs like CGEvent.tapCreate.

No. However, there is nothing stopping you from using Swift Package Manager for just this package even if you normally use CocoaPods or Carthage.

• KeyboardShortcuts (upstream)
• Example app in this fork