Open-source project
sindresorhus/KeyboardShortcuts avatar
sindresorhus/KeyboardShortcuts

KeyboardShortcuts: a macOS 10.15 floor, a macOS 13 feature, and two frozen permalinks

⌨️ Add user-customizable global keyboard shortcuts (hotkeys) to your macOS app in minutes

2,740 stars253 forksSwiftMIT

At a glance

What is it?
A Swift package that adds user-customizable global shortcuts to a macOS app, whose own version section, localization instructions, and documentation links each disagree with something else in the same repository.
Who is it for?
KeyboardShortcuts is worth adopting for a sandboxed Mac App Store app that needs global hotkeys, because the recorder handles persistence and collision warnings and the Cocoa path exists alongside SwiftUI. Check three things first.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 65 days ago.
What is it written in?
Mainly Swift, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • sindresorhus/KeyboardShortcuts2,740 ★ · +22
Star history
Repository2026-10-042026-11-15
sindresorhus/KeyboardShortcuts2.7k2.7k

22 Stars in the last 42 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

Two Tips links point at frozen commits instead of the branch

Two of the Tips entries link to source at a specific commit rather than to the branch. The tip on showing a recorded shortcut in a menu item points into NSMenuItem+KeyboardShortcuts.swift at commit 0dcedd56994d871f243f3d9c76590bfd9f8aba69, lines 14 to 41. The real-world example offered near the top of the usage section points into Plash's PreferencesView.swift at commit b348a62645a873abba8dc11ff0fb8fe423419411, lines 121 to 130. Both are permalinks with the line range baked in, so they describe the source as it stood on those commits and will drift from the tag a developer actually installs. Sitting directly above the first one is an HTML comment that reads as an unfinished task: link to the docs instead when DocC supports showing type extensions. That comment plus the API section, which is nothing but a link to the documentation hosted on a package index, explains why a permalink stands in for a documentation page. The repository tree has no documentation catalog directory of its own, so the generated API reference is not built from anything in this repository. The homepage in the package metadata resolves to that same address on the package index, so the one reference page for the entire public surface sits outside the project. That split is why the runnable demonstration is in the repository instead: the tree carries an example project with its own Xcode project file, Example/KeyboardShortcutsExample.xcodeproj beside Example/KeyboardShortcutsExample.

The stated floor is macOS 10.15 and one documented feature needs 13

The Requirements section states one line, macOS 10.15 and later. One Tips entry needs three major versions more than that. The repeating key down API emits once on the initial press and then repeats using the system key repeat settings, and it carries the parenthetical that it needs macOS 13 or later. Nothing else in the visible text carries an availability annotation, so a project with a deployment target of 10.15 reads a package that claims support for it, adopts an API from the Tips section, and discovers the limit from a parenthesis in prose rather than from a build error or a documented table. The rest of the surface carries no such marker at all, including the events stream for a hard-coded shortcut and the recorder itself. The two user interface paths are treated as equals rather than as one primary and one fallback. The SwiftUI route is a recorder view dropped into a form, and the Cocoa route is a recorder class constructed from a view controller and added as a subview, with its source file named in the text. The three usage snippets together are short enough to support the claim that this fits an app in minutes: register a name, add a recorder, add a listener. The overview also states that the package is fully sandboxed and Mac App Store compatible, and names four apps using it in production, so the package is aimed at shipping rather than at experiments.

The version is written in the readme and again in the tag list

The readme carries its own Version heading with the value 3.1.0, one line, immediately after Requirements. That duplicates the newest tag rather than deriving it, so the two have to be kept in step by hand. The recent tags show how that has gone: 3.0.0 on 2026-06-14, 3.0.1 on 2026-06-17, and 3.1.0 on 2026-09-11, so a major bump and its patch landed three days apart and the minor followed under three months later. The last push is dated 2026-09-11, the same day as the 3.1.0 tag, which means the most recent commit and the most recent release are the same event rather than a release followed by fixes. Two other naming details sit in the same tree: the license file and the readme are both lower case, as license and readme.md, alongside logo-dark.png, logo-light.png, and screenshot.png. The package is otherwise conventionally laid out with Package.swift at the root, Sources, Tests, Example, a .swiftpm directory, a .swiftlint.yml, an .spi.yml, and an .editorconfig. The version heading sits between Requirements and Install rather than in a metadata block at the end, which is why it reads as part of the usage instructions rather than as a property of the package.

The name of a shortcut is a string literal that doubles as its storage key

A shortcut is identified by a member you add to an extension of KeyboardShortcuts.Name, constructed from a string literal, and the same type name is what the recorder persists into UserDefaults. The string is therefore the link between a saved assignment and the call site that asks for it, which is not stated anywhere in the visible text. Renaming the literal, or changing its casing, leaves every previously stored assignment behind under a key nothing reads any more. The Tips section also points out that the extension block is not a requirement. Static registration is described as a convenience so that dot-syntax works at the call site, and names can be created dynamically and stored by the app itself, with the example project showing that in action. So there are two ways to hold a shortcut identity, a compile-time constant keyed by string and a runtime value the app manages, and the package supports both without saying which one to prefer for an app with a changing action list. Enumerating what exists is a third mechanism again. To list shortcut names the type has to be conformed to CaseIterable, which means writing the allCases array by hand, and a second expression then filters that list down to the names that currently have a shortcut assigned, by testing each name's shortcut against nil. So three capabilities need three different pieces of ceremony: an extension to register, a callback to listen, and a protocol conformance plus a hand-maintained array to enumerate.

The recorder warns about collisions, and the readme asks you not to ship defaults

The recorder does two things beyond collecting a key combination. It stores the shortcut in UserDefaults, and it warns the user when the combination they picked is already used by the system or by the app's own main menu. That second behaviour is the reason the package is more than a key capture view, since a global shortcut that shadows a system binding fails silently from the user's point of view otherwise. The opposite case is handled by advice rather than code. The name type accepts an initial value, so a shortcut can ship pre-assigned.

swift
extension KeyboardShortcuts.Name {
	static let toggleUnicornMode = Self("toggleUnicornMode", initial: .init(.k, modifiers: [.command, .option]))
}

The Tips section around it asks you not to use that for a publicly distributed app, on the grounds that users dislike random apps taking shortcuts they already have, and suggests showing a welcome screen on first launch so the user picks the shortcut instead. The parameter exists for migrating from a different package or for personal tools, which is a narrower claim than a default would suggest. The listener placement in the usage example is also not where most people would put it. The onKeyUp registration sits inside the initializer of an observable class marked for the main actor, and that class is held as state in the app type, so the global subscription is installed as a side effect of constructing application state rather than in a view body or a lifecycle method. The closure captures the instance and toggles a property on it, which is what makes it a callback that outlives the initializer it is created in.

Localization is a six step manual procedure with a path that does not match the link

Adding a language is written out as six numbered steps rather than as a build setting. Fork the repository, create a directory named with an ISO 639-1 language code plus optional designators and the .lproj suffix, add a Localizable.strings file under it, copy the contents of the English catalog into it, localize and review the translation more than once for typos, find a speaker of the language to review it, and submit a pull request. Step three names the file to copy from as KeyboardShortcuts/Localization/en.lproj/Localizable.strings, while the link on the line above points at Sources/KeyboardShortcuts/Localization. So the path in the instruction is missing the Sources prefix that the path in the link carries, and a contributor following the text rather than the link looks in the wrong place for the English source. Step five asks contributors to find a native reviewer, which sets a bar the package places on volunteers rather than on a maintainer. No other language code is named in the visible text, so the set of catalogs that already exist cannot be read from the instructions. What can be read is the shape of one: a single Localizable.strings file under a directory named by language code and optional designators, with the English catalog as the template to copy.

The feature set is scoped to one author's own apps, in the author's words

The scope statement sits in the second paragraph of the overview and is unusually direct: what you see here is just what I needed for my own apps, followed by an invitation to accept more configurability and features and a note that pull requests are welcome. That sentence sets the boundary for everything else in the file, and it is consistent with what the Tips section offers. Four entries are labelled dynamic shortcuts, hard-coded shortcuts, repeat while held, and get all shortcuts, which reads as a set of answers to questions one app raised rather than as a designed surface. The same paragraph names the apps it is used in, Dato, Jiffy, Plash, and Lungo, with Plash also used as the worked example elsewhere in the file. The overview claims the package is fully sandboxed and Mac App Store compatible, which is the constraint that shapes the Cocoa recorder as a first-class alternative to the SwiftUI view rather than an afterthought. The four apps are linked from that same paragraph, two of them to pages on the author's own site and two to repositories, so the production claim can be checked by reading those apps rather than by trusting a benchmark. Nothing in the file offers a comparison against other ways of handling global hotkeys on macOS.

Two event streams, and a symbolic representation that reorders modifiers

Listening happens through three surfaces. onKeyUp and onKeyDown cover a named shortcut, a hard-coded shortcut can be watched through an events stream filtered on the event type, and repeatingKeyDownEvents emits once then repeats on the system key repeat settings. The hard-coded path builds a shortcut from a key and a modifier set, then iterates an asynchronous sequence inside a task.

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

That snippet is also the only place the file shows a rendered result, and the result reorders the input: the array is built command first and shift second, while the printed symbols come out shift first. So the symbolic representation is not a straight echo of the order the flags were declared in, which matters if you plan to compare the output against a string. The Tips section's guidance on the hard-coded path is one line, prefer user-customizable shortcuts whenever possible, which is the same preference stated earlier when it asks for a welcome screen instead of shipped defaults. The same snippet that prints modifier symbols also shows reading a shortcut back by name through a getter and printing its modifiers, so the symbolic form is reachable for a shortcut a user assigned and not only for one built by hand. The entry ends there, mid-property-name, with the trailing code unclosed.

Editorial conclusion

KeyboardShortcuts is worth adopting for a sandboxed Mac App Store app that needs global hotkeys, because the recorder handles persistence and collision warnings and the Cocoa path exists alongside SwiftUI. Check three things first. The stated floor is macOS 10.15 while the repeating key down API needs macOS 13, so a deployment target in between gets a package that compiles and a feature that does not fire. The name of a shortcut is a string literal that doubles as the storage key in UserDefaults, so renaming it orphans every saved assignment, which matters on any app that has shipped. And two of the Tips links are pinned to specific commits, so they describe the source as of those commits rather than as of the tag you installed. Authors who want one hard-coded shortcut and nothing else should use the events API directly instead.

Frequently asked questions

Which macOS versions does KeyboardShortcuts support?

The Requirements section states macOS 10.15 and later. One Tips entry needs more than that: the repeating key down API is marked as macOS 13 or later, and no other availability marker appears in the visible text. The package is described as fully sandboxed and Mac App Store compatible.

How do I add a global shortcut to a macOS app with KeyboardShortcuts?

Register a member on KeyboardShortcuts.Name built from a string literal, put a KeyboardShortcuts.Recorder in a settings form so the user can pick a combination, and listen with onKeyUp or onKeyDown. There is a Cocoa equivalent, RecorderCocoa, for apps not using SwiftUI, shown against an AppKit view controller.

Can KeyboardShortcuts ship a default shortcut to users?

The name type accepts an initial value, but the Tips section asks you not to set one for a publicly distributed app, saying users dislike random apps taking shortcuts they already have. It suggests a welcome screen on first launch that lets the user choose instead, and says the parameter is useful when migrating from a different package.

Where does KeyboardShortcuts save the shortcut a user picks?

The recorder stores it in UserDefaults. The name given to a shortcut is a string literal used to construct the name type, so that string is what connects a saved assignment to the code asking for it.

Does KeyboardShortcuts warn about conflicting shortcuts?

Yes. The recorder warns the user if the combination they choose is already used by the system or by the app's main menu, in addition to storing the choice.

How do I get the symbol for a shortcut's modifier keys?

Build an NSEvent.ModifierFlags set and read its symbolic representation. The example in the readme prints shift and command symbols for a set built from command and then shift, so the printed order does not follow the order the flags were declared in.

Official sources

  1. License: MIT
  2. Project website
  3. README
  4. Releases
  5. sindresorhus/KeyboardShortcuts on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/sindresorhus-keyboardshortcuts.svg)](https://hysenlabs.com/projects/sindresorhus-keyboardshortcuts)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/sindresorhus-keyboardshortcuts.svg)](https://hysenlabs.com/projects/sindresorhus-keyboardshortcuts)

Was this useful?