KeyboardShortcuts

When migrating from Magnet, note that Magnet fires on key-down by default. To maintain the same behavior in KeyboardShortcuts, filter your event loop for .keyDown.

Value Migration

If you persisted KeyCombo values manually, convert them using a helper that provides the carbon key code and modifiers.

import KeyboardShortcuts

func migrateLegacyShortcut(
	newName: KeyboardShortcuts.Name,
	readLegacyCarbonValue: () -> (Int, Int)?
) {
	guard KeyboardShortcuts.getShortcut(for: newName) == nil else {
		return
	}

	guard let (carbonKeyCode, carbonModifiers) = readLegacyCarbonValue() else {
		return
	}

	KeyboardShortcuts.setShortcut(.init(carbonKeyCode: carbonKeyCode, carbonModifiers: carbonModifiers), for: newName)
}

To migrate from ShortcutRecorder, replace your recorderControl.bind(...) logic with a SwiftUI KeyboardShortcuts.Recorder.

Value Migration

If your project stores archived shortcut values (common in ShortcutRecorder), keep your existing decoding logic to extract the carbon key code and modifiers, then use the migration pattern used for Magnet to save them into KeyboardShortcuts.

To ensure a smooth transition for users when migrating from another hotkey package, follow this sequence:

1. Check for existing values: Only perform migration if KeyboardShortcuts.getShortcut(for:) == nil to avoid overwriting current user preferences.
2. Write new values: Use KeyboardShortcuts.setShortcut to save the migrated data.
3. Cleanup storage: Remove the old stored value (e.g., from UserDefaults) only after a successful conversion.
4. Remove dependency: Finally, remove the old hotkey package dependency from your project.

When migrating from MASShortcut, note that MASShortcut's binder fires on key-up. To maintain the same behavior in KeyboardShortcuts, filter your event loop for .keyUp.

Value Migration

If you stored MASShortcut objects in UserDefaults, you can migrate them to KeyboardShortcuts by extracting the keyCode and carbonFlags.

import MASShortcut
import KeyboardShortcuts

func migrateMASShortcutValue(oldDefaultsKey: String, newName: KeyboardShortcuts.Name) {
	guard
		KeyboardShortcuts.getShortcut(for: newName) == nil,
		let legacyShortcut = UserDefaults.standard.object(forKey: oldDefaultsKey) as? MASShortcut
	else {
		return
	}

	KeyboardShortcuts.setShortcut(
		.init(
			carbonKeyCode: Int(legacyShortcut.keyCode),
			carbonModifiers: Int(legacyShortcut.carbonFlags)
		),
		for: newName
	)

	UserDefaults.standard.removeObject(forKey: oldDefaultsKey)
}

To use the package for shortcuts that only work when your app is focused (not global), use KeyboardShortcuts.Recorder with a Binding<KeyboardShortcuts.Shortcut?>. You must manage the persistence (e.g., via @AppStorage) yourself.

import SwiftUI
import KeyboardShortcuts

struct ContentView: View {
    @State private var shortcut: KeyboardShortcuts.Shortcut?

    var body: some View {
        VStack {
            KeyboardShortcuts.Recorder("Record shortcut", shortcut: $shortcut)
            Button("Perform Action") {
                performAction()
            }
            .keyboardShortcut(shortcut?.toSwiftUI)
        }
    }
}

If you need to listen to a specific, non-user-customizable global shortcut, you can listen to a KeyboardShortcuts.Shortcut directly using KeyboardShortcuts.events(for:).

import KeyboardShortcuts

let shortcut = KeyboardShortcuts.Shortcut(.a, modifiers: [.command])

Task {
    for await eventType in KeyboardShortcuts.events(for: shortcut) where eventType == .keyUp {
        // Do something.
    }
}

You can convert NSEvent.ModifierFlags or a KeyboardShortcuts.Shortcut's modifiers into a symbolic string representation (e.g., "⇧⌘") using the ks_symbolicRepresentation property.

import KeyboardShortcuts

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

if let shortcut = KeyboardShortcuts.getShortcut(for: .toggleUnicornMode) {
    print(shortcut.modifiers.ks_symbolicRepresentation)
    //=> "⌘⌥"
}

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.ks_symbolicRepresentation)
    //=> "⌘⌥"
}

To perform repeated actions while a shortcut is held down, use KeyboardShortcuts.repeatingKeyDownEvents(for:). This emits once on the initial press and then repeats according to the system's key repeat settings.

import KeyboardShortcuts

Task {
    for await _ in KeyboardShortcuts.repeatingKeyDownEvents(for: .moveSelectionDown) {
        // Move to the next item.
    }
}

If you are using AppKit instead of SwiftUI, use KeyboardShortcuts.RecorderCocoa to provide a shortcut recording interface in your NSViewController.

import AppKit
import KeyboardShortcuts

final class SettingsViewController: NSViewController {
    override func loadView() {
        view = NSView()

        let recorder = KeyboardShortcuts.RecorderCocoa(for: .toggleUnicornMode)
        view.addSubview(recorder)
    }
}