A Hyper Key with Karabiner Elements, full instructions
Yesterday I posted excitedly about full Hyper key functionality being available in macOS 10.12+. I included a snippet of a config file that has apparently led to some confusion, so I’m elaborating here on the full configuration.
As of 2024, there’s a new option that you might find useful for this purpose (and more) called SuperKey. Check it out if this route seems like a hassle, or if you just want to see more cool apps for your Mac.
The first thing you need is Karabiner Elements, and you need what is currently the bleeding edge version, 0.91.3. If you don’t already have Karabiner Elements installed, grab the latest version at pqrs.org/latest/karabiner-elements-latest.dmg. Open Karabiner Elements and go to the Misc tab, you can check your version and update if needed by clicking the “Check for beta updates” button.
Once it’s running, there’s a configuration file at ~/.config/karabiner/karabiner.json that you can edit. The options required for this are not available yet in the GUI, so they have to be added into this hidden config file.
The file is JSON, and breaking the formatting will cause Karabiner failure, so be sure to do any editing with care. Below is a complete version of my config file. It has no significant changes from the default other than the Hyper Key functionality. If you don’t have any other settings in Karabiner (e.g. Simple Modifications beyond one that, say, maps caps lock to something for Hammerspoon…), you can overwrite the contents of the karabiner.json with the code below.
If you do have other settings, you’ll need to follow different directions, so skip to the next part.
{
"global": {
"check_for_updates_on_startup": true,
"show_in_menu_bar": true,
"show_profile_name_in_menu_bar": false
},
"profiles": [
{
"complex_modifications": {
"rules": [
{
"manipulators": [
{
"description": "Change caps_lock to command+control+option+shift.",
"from": {
"key_code": "caps_lock",
"modifiers": {
"optional": [
"any"
]
}
},
"to": [
{
"key_code": "left_shift",
"modifiers": [
"left_command",
"left_control",
"left_option"
]
}
],
"to_if_alone": [
{
"key_code": "escape"
}
],
"type": "basic"
}
]
}
]
},
"devices": [
{
"disable_built_in_keyboard_if_exists": false,
"identifiers": {
"is_keyboard": true,
"is_pointing_device": false,
"product_id": 610,
"vendor_id": 1452
},
"ignore": false
},
{
"disable_built_in_keyboard_if_exists": false,
"identifiers": {
"is_keyboard": true,
"is_pointing_device": false,
"product_id": 597,
"vendor_id": 1452
},
"ignore": false
}
],
"fn_function_keys": {
"f1": "vk_consumer_brightness_down",
"f10": "mute",
"f11": "volume_down",
"f12": "volume_up",
"f2": "vk_consumer_brightness_up",
"f3": "vk_mission_control",
"f4": "vk_launchpad",
"f5": "vk_consumer_illumination_down",
"f6": "vk_consumer_illumination_up",
"f7": "vk_consumer_previous",
"f8": "vk_consumer_play",
"f9": "vk_consumer_next"
},
"name": "Default profile",
"one_to_many_mappings": {},
"selected": true,
"simple_modifications": {},
"standalone_keys": {},
"virtual_hid_keyboard": {
"caps_lock_delay_milliseconds": 0,
"keyboard_type": "ansi",
"standalone_keys_delay_milliseconds": 200
}
}
]
}
To edit just the Hyper key chunk into an existing config, you’ll add the chunk below into the “profiles” array in the first element:
Here’s the chunk that you’ll paste in. Be sure to keep the trailing comma after the last curly bracket.
"complex_modifications": {
"rules": [
{
"manipulators": [
{
"description": "Change caps_lock to command+control+option+shift. Escape if no other key used.",
"from": {
"key_code": "caps_lock",
"modifiers": {
"optional": [
"any"
]
}
},
"to": [
{
"key_code": "left_shift",
"modifiers": [
"left_command",
"left_control",
"left_option"
]
}
],
"to_if_alone": [
{
"key_code": "escape",
"modifiers": {
"optional": [
"any"
]
}
}
],
"type": "basic"
}
]
}
]
},
Karabiner Elements should immediately detect the change and your Hyper Key should start working. You can test by going into any app that lets you assign keyboard shortcuts, such as BetterTouchTool, and adding or editing one. Holding down Caps Lock and hitting a key should give you the result ⌘⇧⌥⌃X. Hitting Caps Lock once should give you ⎋ (Escape).
Note that you should be able to modify the Escape part of the key to maintain Caps Lock functionality by changing to “to_when_alone” value in the JSON to “caps_lock”. Then hitting Caps Lock with no other key should still allow it to function as normal.
If you have issues, be sure to check that in System Preferences->Keyboard->Modifier Keys you’ve disabled Caps Lock (set it to No Action). Note that if you use multiple keyboards (like the internal laptop one and an external Bluetooth one), that screen will have a dropdown where you’ll need to set this for each available keyboard. Also ensure that you don’t have any “simple modifications” set in Karabiner Elements that would be trapping the Caps Lock key.
Hopefully that’s a bit clearer…
Brett is a writer and developer living in Minnesota, USA. You can follow him as ttscoff on Twitter, GitHub, and Mastodon. Sign up for the email newsletter, and keep up with this blog by adding it to your favorite news reader.