Repolode
Submit
sindresorhus

sindresorhus/KeyboardShortcuts

A Swift package that lets macOS apps add user-customizable global keyboard shortcuts with a ready-made recorder UI.

View on GitHubWebsite
Stars
2,736
Forks
253
Open issues
3
Last commit
2 months ago

What is it?

KeyboardShortcuts is a Swift package for macOS apps that need global keyboard shortcuts the user can change. You define a named shortcut once, drop a SwiftUI or Cocoa recorder view into your settings screen, and register a handler for key down or key up events. The package stores the chosen shortcut in UserDefaults and warns the user when a combination is already used by the system or the app's main menu.

The package is sandboxed and compatible with the Mac App Store, and it does not trigger permission dialogs. It also includes helpers for showing a recorded shortcut in an NSMenuItem, converting modifier flags to symbols, listening to hard-coded shortcuts, and repeating actions while a key is held on macOS 13+.

It targets macOS 10.15 and later and is installed through Swift Package Manager. Limitations include no support for media keys in sandboxed apps and no way to listen to the Caps Lock key through the standard API.

Key features

  • 01Provides a SwiftUI Recorder view and a Cocoa RecorderCocoa view for capturing shortcuts.
  • 02Persists user-chosen shortcuts in UserDefaults automatically.
  • 03Warns users about conflicts with system shortcuts and the app's main menu.
  • 04Supports listening to key down and key up events.
  • 05Can attach a recorded shortcut to an NSMenuItem.
  • 06Installs via Swift Package Manager.

Use cases

  • Adding a user-configurable global hotkey to a menu bar utility.
  • Letting users customize shortcuts in a macOS app's preferences window.
  • Adding in-app shortcuts that users can record and store with their own storage.

Quick start

  1. 1

    Add the package in Xcode via the Swift Package Manager tab using the repository URL

  2. 2

    Register a shortcut name, then add a Recorder view in your settings screen

  3. 3

    Listen for the shortcut with onKeyUp or onKeyDown

Things to know

  • Only works on macOS 10.15 and later, so it is not for other platforms.
  • Global shortcuts use Carbon APIs that Apple has not replaced, and media keys are not supported in sandboxed apps.

In collections

Open-source Mac apps

Topics

#macos#swift#keyboard-shortcuts#hotkey#swiftui#swift-package-manager#carthage#cocoapods#swift-package#swiftui-components

FAQ

What is KeyboardShortcuts?
A Swift package that lets macOS apps add user-customizable global keyboard shortcuts with a ready-made recorder UI. KeyboardShortcuts is a Swift package for macOS apps that need global keyboard shortcuts the user can change. You define a named shortcut once, drop a SwiftUI or Cocoa recorder view into your settings screen, and register a handler for key down or key up events. The package stores the chosen shortcut in UserDefaults and warns the user when a combination is already used by the system or the app's main menu.
Is KeyboardShortcuts free to use? What license does it have?
KeyboardShortcuts is open source under the MIT license. Check the license terms before using it in commercial products.
Is KeyboardShortcuts still maintained?
Updated within 6 months. The last commit to KeyboardShortcuts was on Sep 11, 2026.
What can I use KeyboardShortcuts for?
Adding a user-configurable global hotkey to a menu bar utility. Letting users customize shortcuts in a macOS app's preferences window. Adding in-app shortcuts that users can record and store with their own storage.
How do I install KeyboardShortcuts?
Add the package in Xcode via the Swift Package Manager tab using the repository URL Register a shortcut name, then add a Recorder view in your settings screen Listen for the shortcut with onKeyUp or onKeyDown
Where can I get KeyboardShortcuts?
The source code and installation instructions are on GitHub: https://github.com/sindresorhus/KeyboardShortcuts

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects