How to remap your mouse keys using karabiner on macOS

3 min readJun 9, 2020


I’ve been using my MacBook Pro connected with an external monitor, keyboard and mouse for 3 months and I love this setup.

I already talked about Karabiner in a previous blog post, I used this tool to remap some keys of my keyboard.

As I said I also use an external mouse, it is a cheap vertical mouse produced by Aukey and as you can see from this photo it has 3 buttons that are completely useless on macOS and if I click them nothing happens.

After some months I thought that I could use these three buttons to do something useful, more specifically I wanted to remap the keys in the following way:

  • Button 4 to go backwards in Safari
  • Button 5 to go forward in Safari
  • Button 3 to close the current tab in Safari

To remap the keys of my mouse I decided to Karabiner, again.

In this case, the setup is a bit harder than the one I talked about in the previous post and we have to change the Karabiner’s configuration file.
More specifically I changed the “karabiner.json” file.

Karabiner Event Viewer

Before we start with the code I want to talk a little bit about the Karabiner Event Viewer. This tool helped me a lot because it allowed me to understand Firefox’s Bundle Identifier (we’ll see later why I needed this information) and it also allowed me to debug the configuration.
You can open the Event Viewer from the Karabiner’s icon that you should have in the status bar.

As you can see from the image, using the Event Viewer you can precisely understand what happens when you press a button on your keyboard or on your mouse.

Let’s write the configuration file

Into the karabiner.json file, we have to add some pieces of information in the “complex_modifications” field.

Into this section of the JSON file, we have to add some rules to remap the mouse’s button.

As an example, I’ll put here some snippets taken from my configuration. You can find the entire file in this Github repository.

  • First of all, I wanted to use the “button4” to go back to the previous page in Safari. After I wrote this rule I discovered that it also works in the Finder but it does not work in Firefox because Firefox does not support this shortcut (I wrote a different rule for it).
    In this rule I had to add a condition, the rule works only if the frontmost application is different than Firefox.
    In this case when I press the “button4” I simulate the shortcut CMD+[+ALT that is used in Safari to go to the previously visited page.
    The go Forward shortcut is similar to the previous one, in this case, I remap the “button5” to run the shortcut CMD+]+ALT.
  • As I said Firefox has a different shortcut to go backward to the previously visited page so I had to write a different rule.
    In this case, in the condition, I use the type “frontmost_application_if” because I want to execute the shortcut if and only if Firefox is the frontmost application. In this case, I remap the “button5” to the shortcut CMD+left arrow.
  • The last rule I want to talk about is the one that I wrote to close the current tab. In this case, when I press the “button3” I want to execute the shortcut CMD+W.

Obviously, you can extend this configuration and you can also use the mouse buttons combined with other keyboard keys to execute any other shortcut.




Computer Science student 🎓👨🏻‍💻🎧