sindresorhus/KeyboardShortcuts

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. And it's used in production by Dato, Jiffy, Plash, and Lungo.

I'm happy to accept more configurability and features. PRs welcome! What you see here is just what I needed for my own apps.

Requirements

macOS 10.15+

Version

3.0.1

Install

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

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.

SettingsScreen.swift

import SwiftUI
import KeyboardShortcuts

struct SettingsScreen: View {
    var body: some View {
        Form {
            KeyboardShortcuts.Recorder("Toggle Unicorn Mode:", name: .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.

App.swift

import SwiftUI
import KeyboardShortcuts

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

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

@MainActor
@Observable
final class AppState {
    init() {
        KeyboardShortcuts.onKeyUp(for: .toggleUnicornMode) { [self] in
            isUnicornMode.toggle()
        }
    }
}

You can also listen to key down with .onKeyDown()

That's all! ✨

You can find a complete example in the “Example” directory.

You can also find a real-world example in my Plash app.

Cocoa

Using KeyboardShortcuts.RecorderCocoa instead of KeyboardShortcuts.Recorder:

import AppKit
import KeyboardShortcuts

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

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

Localization

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 KeyboardShortcuts/Localization/en.lproj/Localizable.strings to the new file that you just created.
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.

API

See the API docs.

Tips

Show a recorded keyboard shortcut in an NSMenuItem

See NSMenuItem#setShortcut.

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 KeyboardShortcuts.Name's dynamically and store them yourself. You can see this in action in the example project.

Hard-coded keyboard shortcuts

If you need a hard-coded global shortcut, you can listen to a KeyboardShortcuts.Shortcut directly.

import KeyboardShortcuts

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

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

Prefer user-customizable shortcuts whenever possible.

Repeat while held

If you need repeated actions while the shortcut is held, use repeatingKeyDownEvents(for:). It emits once on initial press, then repeats using the system key repeat settings. (macOS 13+)

import KeyboardShortcuts

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

Initial keyboard shortcuts

Setting an initial 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", initial: .init(.k, modifiers: [.command, .option]))
}

Get all keyboard shortcuts

To get all the keyboard shortcut Name's, 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 the Name's with a set keyboard shortcut:

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

Convert modifier flags to symbols

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

FAQ

How is it different from MASShortcut?

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

MASShortcut:

• More mature.
• More localizations.

Why is this package importing Carbon? Isn't that deprecated?

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.

Can I use this for customizable in-app keyboard shortcuts?

Yes. Use KeyboardShortcuts.Recorder with a Binding<KeyboardShortcuts.Shortcut?> to let users record a shortcut without registering any global hotkey, then apply it with .keyboardShortcut(shortcut?.toSwiftUI). The shortcut only fires when your app is focused. To persist it across launches, save it to UserDefaults or @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)
        }
    }
}

Can I use custom storage for shortcuts?

Yes. Use KeyboardShortcuts.Recorder with shortcut: Binding<KeyboardShortcuts.Shortcut?> to read and write shortcuts from your own storage, and use KeyboardShortcuts.events(for: shortcut) to listen to those shortcuts.

Does it support media keys?

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

Can I listen to the Caps Lock key?

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.

Can you support CocoaPods or Carthage?

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

Related

• Defaults - Swifty and modern UserDefaults
• LaunchAtLogin - Add "Launch at Login" functionality to your macOS app
• More…