Karabiner-elements: How to create your own CUSTOM complex modifications?

[neilpanchal]

Presumably, I am in the minority here? I can't seem to find out how to create my own custom modification.

Help file doesn't help: https://pqrs.org/osx/karabiner/document.html#configuration-complex-modifications

It mentions briefly that "or create your own" but doesn't actually tell you. Google search didn't turn up any useful results.

The app only allows me to import from https://pqrs.org/osx/karabiner/complex_modifications/

which again, doesn't instruct the user about how to create one from scratch.

I've since modified the .json in ~/.config/karabiner/custom_modifications file by installing something similar off of the official repository.

As a feedback, it is __critical__ to put a note somewhere in the main application that informs the average joe using this app about how to create a new custom modification. I was completely lost and I am still lost, but I managed to modify the .json file and for now this is ok.

[tekezo]

Here: https://pqrs.org/osx/karabiner/json.html

[neilpanchal]

@tekezo Thank you. This needs to be included somewhere in the GUI or the Karabiner official repository of complex modifications.

[grrowl]

Would be great to have that document more prominently linked. Had to reverse engineer adding one from web but substituting for a file:/// URL instead. It works :)

[RochelleBS]

Sorry to be a dolt, Tekezo, but I don't understand how to create a complex modification from scratch. Can you please give some total newbie step-by-steps? I'm guessing this doesn't use the GUI to actually create the modifications, but only to turn them on or off.

[grrowl]

1. Read the docs at https://pqrs.org/osx/karabiner/json.html
2. Edit the file at ~/.config/karabiner/karabiner.json. It will include all currently enabled rules (so it might be a very big file), but you can edit and add new complex modifications there.
3. This file is reloaded by Karabiner Elements on every save, so you can test. It will help to open Karabiner Elements > Log, and check for any red errors (which may indicate incorrect config values or keys, or other problems with your modifications)

[RochelleBS]

Thank you.

Tom McKenzie wrote:
>

1. Read the docs at https://pqrs.org/osx/karabiner/json.html
2. Edit the file at |~/.config/karabiner/karabiner.json|. It will
   include all currently enabled rules (so it might be a very big
   file), but you can edit and add new complex modifications there.
3. This file is reloaded by Karabiner Elements on every save, so you
   can test. It will help to open Karabiner Elements > Log, and check
   for any red errors (which may indicate incorrect config values or
   keys, or other problems with your modifications)

—
You are receiving this because you commented.
Reply to this email directly, view it on GitHub
https://github.com/tekezo/Karabiner-Elements/issues/1225#issuecomment-359306748,

or mute the thread
https://github.com/notifications/unsubscribe-auth/AiA03YfZjZufmEsi7fSGcTPW92wiKPk1ks5tM-8hgaJpZM4RdtXU.

[NPatrakov]

hello to all! Please help me. i`m going crazy with new version of karabiner. what to insert to json file to do
Change Option_R+,(≤) to Comma(,) Key for Russian
Change Option_R+,(≥) to Dot(.) Key for Russian
@tekezo

[prohtex]

@tekezo How about bringing this button back?

[YayC]

To make these persist across updates, I tried adding a new file: ~/.config/karabiner/assets/complex_modifications/mine.json (using an imported file as an example). This seems to be working fine after enabling it from the preferences > complex modifications tab, but I have not updated since to test persistence.

Should this be the supported method for adding custom complex modifications?

[babarrett]

Yes, YayC's creation / edit of ~/.config/karabiner/assets/complex_modifications/mine.json should be included within: https://pqrs.org/osx/karabiner/json.html

I also noticed that in order to do an edit / run cycle I needed to:

1. edit ...mine.json
2. "remove" the active custom complex_modifcations I'd already enabled for that file in the preferences
3. re-enable those complex_modifcations in the preferences

Without that the edited code seems not be reloaded. :-(

[llamerr]

Something like "Import JSON from file" inside "Add rule" would be very useful

[egstad]

I'm looking to create a complex modification that converts the fn + spacebar keys into a backspace, however i'm not having any luck. I've played around with other key_codes and mandatory keys and the rule works great. Have I missed something?

{
    "from": {
        "key_code": "spacebar",
        "modifiers": {
            "mandatory": [
                "fn"
            ]
        }
    },
    "to": [
        {
            "key_code": "delete_or_backspace"
        }
    ],
    "type": "basic"
}

[crawfyp1]

Good evening

Total noob here. I would like to swap @ and " on my keyboard. I assume this is a complex modification as it involves shift and another key?

I have tried simple modification but cant achieve what I'm looking to do. I have read the complex modification instructions but I'm not a coder and it's totally beyond my skill set.

Can anyone help me? I can follow step by step instructions, or could someone upload so I can download from the complex mod import site?

Very grateful for any help

[HBinswanger]

I have an XML profile from the pre-Sierra version. It has lots of carefully crafted code. I don't see how to import that into the Elements or translate it to something Elements can use. I'm a newbie; help would be greatly appreciated.

[revelt]

@jordanegstad I think there's a rule which prohibits all-function-key combos (like CMD+ALT+CTRL), there has to be a non-functional key in the key combo. As a last resort, try sacrificing F12 for example, remapping it as fn, then map F12+spacebar instead. Maybe that would work? I toggle my terminal using caps lock this way: remapped my caps lock key to press F12 (in Karabiner), then mapped F12 to toggle terminal (in Terminal app).

@crawfyp1 Did you follow https://pqrs.org/osx/karabiner/document.html#configuration-simple-modifications ? If so, where did you get stuck? Please attach screenshots.

@HBinswanger the Karabiner Elements config is located at ~/.config/karabiner/karabiner.json. If you know where your XML profile is, the task becomes to port it to Elements. I'm not familiar with XML profiles but if they are really in XML, the Elements config is in JSON, so you will have to manually re-create all your customisations in ~/.config/karabiner/karabiner.json. If profile is in JSON, carefully port them one at the time, making sure JSON key structure is matching Karabiner Elements config (there's rules key, it's equal to array, there's object with manipulators key which contains array of all customisations...)

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[ianklatzco]

Sorry for the necropost, but for anyone coming by later:

• If you have a properly formatted JSON file (pip3 install demjson; jsonlist file.json) matching the format, you can put it in ~/.config/karabiner/assets/complex_modifications with whatever name. When you click Add Rule in the Complex Modifications pane, you should see it in the list.

• Alternatively, You can use a Karabiner link to import configs, using a file URL (as mentioned earlier in this thread).

• Note that it needs to be url-encoded: open python and urllib.parse.quote("file:///... (or just switch the : for a %3A)
• Load this in your browser: karabiner://karabiner/assets/complex_modifications/import?url=file%3A///Users/YOUR_USERNAME/.config/karabiner/assets/complex_modifications/FILENAME.json

[HBinswanger]

I just want to use shifted states to output one or two keystrokes. E. G to have ctrl-y do the few keystrokes that will delete a line. Do I have to jump thru these hoops to do that? Suppose I want ctrl-shift-x to put out Ab followed by the Enter key. What would the JSON look like exactly?
Sent from my iPhone

On Feb 4, 2019, at 3:49 AM, ian klatzco [e-mail] wrote:

Sorry for the necropost, but for anyone coming by later:

If you have a properly formatted JSON file (pip3 install demjson; jsonlist file.json) matching the format, you can put it in ~/.config/karabiner/assets/complex_modifications with whatever name. When you click Add Rule in the Complex Modifications pane, you should see it in the list.

Alternatively, You can use a Karabiner link to import configs, using a file URL (as mentioned earlier in this thread).

Note that it needs to be url-encoded: open python and urllib.parse.quote("file:///... (or just switch the : for a %3A)

Load this in your browser: karabiner://karabiner/assets/complex_modifications/import?url=file%3A///Users/YOUR_USERNAME/.config/karabiner/assets/complex_modifications/FILENAME.json

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub, or mute the thread.

[AdamWagner]

@HBinswanger - I recommend using DefaultKeyBindings.dict for that. See https://brettterpstra.com/projects/keybindings/

[ghost]

Hi everyone! I'm sorry to annoy you all, a complete noob here!

I'm using an AZERTY keyboard and the acute accent mark is quite troublesome to get.

I was looking for a modification like:

[ option + ' ] -> [ option + shift + & ]

Can anybody help me pleeeeeease!

[euclid1990]

@jonasbaraujo You can see this example

https://gist.github.com/euclid1990/ee6ed30164c8936f0cecba0194b1b8b4

Put it into karabiner.json > profiles > complex_modifications

[HBinswanger]

@HBinswanger - I recommend using DefaultKeyBindings.dict for that. See https://brettterpstra.com/projects/keybindings/

Thank you. I found the Karabiner stuff several screenfuls down several. Unfortunately, it's overkill--I just wanted a single example to use as a template. I got that from jonasbaraujo.

[HBinswanger]

@jonasbaraujo You can see this example

https://gist.github.com/euclid1990/ee6ed30164c8936f0cecba0194b1b8b4

Put it into karabiner.json > profiles > complex_modifications

Thank you! This is exactly what I need.

[tilo]

why is there no way to just provide the JSON from a local file??
Seems unnecessarily complicated to have to go through web-download of rules

[araa47]

@tilo , just edit the ~/.config/karabiner/karabiner.json file

[linonetwo]

Can you add a button on GUI to open ~/.config/karabiner/karabiner.json?

That button can just simply execute open ~/.config/karabiner/karabiner.json, this is enough.

[benjaminb]

Hi folks, very new to Karabiner and having trouble getting it to accept complex modifications. I've added the following to ~/.config/karabiner/karabiner.json under "rules", under "complex_modifications", but it's not taking effect. Is there something else I need to do? The docs say Karabiner should pick up the change on save.

        "rules": [{
            "description": "command-backslash to end",
            "manipulators": [{
                "from": {
                    "key_code": "backslash"
                    "modifiers": ["left_command"]
                },
                "to": [{
                    "key_code": "end"
                }],
                "type": "basic"
            }]
        }]

[chmreid]

Any updates on this request?

This needs to be included somewhere in the GUI or the Karabiner official repository of complex modifications.

After 1.5 years this is still where I end up when searching for "How to implement custom modifications karabiner"

[avalanche1]

Just added several custom bindings, using unsystemated info here. So here is a working instruction:

• create a custom .json file in ~/.config/karabiner/assets/complex_modifications
• fill the file with your instructions (see example below); more examples here; but note, that they don't provide the exact file structure, only rules - use my structure below
• goto Karabiner -> Preferences -> Complex Modifications -> Add rule
• enable your custom rule(s)
• PROFIT!!

{
  "title": "KAT",
  "rules": [
    {
      "description": "hl to start\\end of line; uo for pgup\\pgdown",
      "manipulators": [
        {
          "from": {
            "key_code": "h",
            "modifiers": {
              "mandatory": ["fn"]
            }
          },
          "to": [
            {
              "key_code": "left_arrow",
              "modifiers": ["command"]
            }
          ],
          "type": "basic"
        },
        {
          "from": {
            "key_code": "semicolon",
            "modifiers": {
              "mandatory": ["fn"]
            }
          },
          "to": [
            {
              "key_code": "right_arrow",
              "modifiers": ["command"]
            }
          ],
          "type": "basic"
        },
        {
          "from": {
            "key_code": "u",
            "modifiers": {
              "mandatory": ["fn"]
            }
          },
          "to": [
            {
              "key_code": "page_up"
            }
          ],
          "type": "basic"
        },
        {
          "from": {
            "key_code": "o",
            "modifiers": {
              "mandatory": ["fn"]
            }
          },
          "to": [
            {
              "key_code": "page_down"
            }
          ],
          "type": "basic"
        }
      ]
    }
  ]
}

[Rainymood]

As a newcomer, this is still unclear. From the current manual it seems that you can not make your own custom complex commands, only those that are uploaded to the webpage. I know this is not true, but it appears to be so for the newcomer.

[matthewblott]

@Rainymood yep, that's just thrown me

[ProfBobK]

To try and get the hang of things I downloaded one of the .json files from the web page opened by 'import more rules from the internet', and copied it into ~/.config/karabiner/assets/complex_modifications as 'tmp.json'. It does not show up as a rule I can add. Why? What else do I need to do?

[mhldr]

I found ~/.config/karabiner/assets/complex_modifications/mine.json wasn't picked up.
If you enable an example complex modification then you'll see it added into ~/.config/karabiner.json then you can just modify the karabiner.json (after taking a copy).
So my karabiner.json goes as

{
    "global": {
        "check_for_updates_on_startup": false,
        "show_in_menu_bar": true,
        "show_profile_name_in_menu_bar": false
    },
    "profiles": [
        {
            "complex_modifications": {
                "parameters": {
                    "basic.simultaneous_threshold_milliseconds": 50,
                    "basic.to_delayed_action_delay_milliseconds": 500,
                    "basic.to_if_alone_timeout_milliseconds": 1000,
                    "basic.to_if_held_down_threshold_milliseconds": 500,
                    "mouse_motion_to_scroll.speed": 100
                },
                "rules": [
                {
                  "description": "home to start of line / end to end of line",
                  "manipulators": [
                    {
                      "from": {
                        "key_code": "home"
                      },
                      "to": [
                        {
                          "key_code": "left_arrow",
                          "modifiers": ["command"]
                        }
                      ],
                      "type": "basic"
                    },
                    {
                      "from": {
                        "key_code": "end"
                      },
                      "to": [
                        {
                          "key_code": "right_arrow",
                          "modifiers": ["command"]
                        }
                      ],
                      "type": "basic"
                    }
                  ]
                }
              ]
            },
            "devices": [],
            "fn_function_keys": [
                {
....

[lucask42]

I was bashing my head on the desk unable to get any complex modifications to work. Was almost going to give up when I found some checkboxes under Devices > Basic Configuration. The checkbox next to my bluetooth keyboard was unchecked, after checking this box my complex modifications started working as expected.

[0xMH]

This hasn’t been properly solved IMHO. For newcomers, Here's the updated link for the docs https://karabiner-elements.pqrs.org/docs/json/

[spacesuitdiver]

This hasn’t been properly solved IMHO. For newcomers, Here's the updated link for the docs https://karabiner-elements.pqrs.org/docs/json/

I honestly don't think this article solves this as a newcomer, I had to refer to https://github.com/pqrs-org/Karabiner-Elements/issues/1225#issuecomment-571579064 still 🙁

[colossatr0n]

This hasn’t been properly solved IMHO. For newcomers, Here's the updated link for the docs https://karabiner-elements.pqrs.org/docs/json/

I've updated the reference manual a bit to help with adding complex modifications that can be added or disabled through the UI: https://karabiner-elements.pqrs.org/docs/json/root-data-structure/

[DrNeroCF]

Would be nice to at least have a link to the json file in the GUI.

I only need to add modifier keys a command, is there a way to do that in the simple modification / GUI that I'm missing?

[assist726]

You know there's something seriously wrong with your documentation and GUI when people constantly have to resort to looking through closed issues to find something as basic as this

@tekezo

[rr1000]

I purchased a new mechanical keyboard for my mac and need to remap "space + ESC" to "space + `" since this keyboard doesn't have a dedicated tilde key and I don't want to hit three keys "space + fn1 + ESC" to move between multiple windows. Since Karabiner seems all but dead, does anyone have recommendations for replacement software? Even if it's paid.

[babarrett]

I still have Karabiner on my system, but also use: Hammerspoon.

[Rainymood]

I didn't know how to make a complex modification a year ago, so I made a short video as a piece of documentation. I hope you find it useful!

https://www.youtube.com/watch?v=iiSIaMD4vqY

[djeikyb]

Why is this closed? There's still no documentation, and it really looks like there's no way to write your own complex modification

[oakif]

Just a note for anyone reading this—your modification won't show up if you have syntax errors in your json file. The modification will silently be hidden from the modification list.

[ericjung]

I didn't know how to make a complex modification a year ago, so I made a short video as a piece of documentation. I hope you find it useful!

https://www.youtube.com/watch?v=iiSIaMD4vqY

This is great! Here is a text version created from your video.

As of November 2020, Karabiner Elements 13.1.0 and macOS BigSur 11.0.1:

1. Create a new file in a text editor.
2. Enter mappings. You might have trouble with this format if you're not a programmer. Use https://karabiner-elements.pqrs.org/docs/json/complex-modifications-manipulator-definition/ as a reference but understand that it only describes the manipulators array. The JSON struct must be an object with a rules array whose elements are objects with a manipulators array.

Here is a _complete_ example:

{
    "title": "windows-style keyboard for macOS",
    "rules": [
      {
        "description": "application and tab switching",
        "manipulators": [
          {
            "type": "basic",
            "from": {
              "key_code": "tab",
              "modifiers": {
                "mandatory": ["left_option", "shift"],
                "optional": ["caps_lock"]
              }
            },
            "to": [
              {
                "key_code": "tab",
                "modifiers": ["left_command", "shift"]
              }
            ]
          },
          {
            "type": "basic",
            "from": {
              "key_code": "tab",
              "modifiers": {
                "mandatory": ["left_option"],
                "optional": ["caps_lock"]
              }
            },
            "to": [
              {
                "key_code": "tab",
                "modifiers": ["left_command"]
              }
            ]
          },
          {
            "type": "basic",
            "from": {
              "key_code": "tab",
              "modifiers": {
                "mandatory": ["left_command"]
              }
            },
            "to": [
              {
                "key_code": "tab",
                "modifiers": ["left_control"]
              }
            ]
          },
          {
            "type": "basic",
            "from": {
              "key_code": "tab",
              "modifiers": {
                "mandatory": ["left_command", "shift"]
              }
            },
            "to": [
              {
                "key_code": "tab",
                "modifiers": ["left_control", "shift"]
              }
            ]
          }                     
        ]
      },
      {
        "description": "Swap Command with Ctrl",
        "manipulators": [
          {
            "type": "basic",
            "from": {
              "key_code": "left_command",
              "modifiers": {
                "optional": [
                  "any"
                ]
              }
            },
            "to": [
              {
                "key_code": "left_control"
              }
            ]
          },
          {
            "type": "basic",
            "from": {
              "key_code": "left_control",
              "modifiers": {
                "optional": [
                  "any"
                ]
              }
            },
            "to": [
              {
                "key_code": "left_command"
              }
            ]
          },
          {
            "type": "basic",
            "from": {
              "key_code": "left_shift",
              "modifiers": {
                "optional": [
                  "any"
                ]
              }
            },
            "to": [
              {
                "key_code": "left_shift",
                "lazy": true
              }
            ]
          },
          {
            "type": "basic",
            "from": {
              "key_code": "right_command",
              "modifiers": {
                "optional": [
                  "any"
                ]
              }
            },
            "to": [
              {
                "key_code": "right_control"
              }
            ]
          },
          {
            "type": "basic",
            "from": {
              "key_code": "right_control",
              "modifiers": {
                "optional": [
                  "any"
                ]
              }
            },
            "to": [
              {
                "key_code": "right_command"
              }
            ]
          },
          {
            "type": "basic",
            "from": {
              "key_code": "right_shift",
              "modifiers": {
                "optional": [
                  "any"
                ]
              }
            },
            "to": [
              {
                "key_code": "right_shift",
                "lazy": true
              }
            ]
          }
        ]
      }      
    ]
  }

1. Check the syntax of your file by copying/pasting it into a JSON beautifier. If you don't do this and your file has a syntax error, Karabiner won't parse your file and silently ignores it (although the Log tab sometimes does display errors, but it was not consistent for me). There are many available on the web, such as this one.

2. Save File to ~/.config/karabiner/assets/complex_modifications/any_filename.json -- any_filename can be anything you want, but keep the .json extension.

3. In Karabiner Elements, goto the Complex Modifications tab. Click Add Rule. Looks for your rules and click Enable next to each.