8BitDo Retro R8 Mouse · Karabiner-Elements

Retro R8 MacMap

Rules that make the Retro R8 Mouse work properly on macOS. All four side buttons become usable, including the two that send nothing at all out of the box, and every rule is scoped to this mouse alone.

---

Open the rule builder

Pick an action for each button and it assembles the complete file. Opens loaded with the configuration below rather than empty. Runs entirely in your browser.

What it does out of the box

Button	Becomes
Button 4	Back
Button 5	Delete (backspace)
Button 5 + Ctrl	Delete forward
Wheel press	Return
Buttons 6 and 7	yours to assign

Back and Delete on the thumb buttons is a preference, not a recommendation. Swapping it is a one-line edit, and the builder does it for you.

Setup, in four steps

1. Tick "Modify events" for every Retro R8 row in Karabiner-Elements → Devices. The mouse presents two interfaces and each has its own checkbox — missing one is why the wheel press appears dead.
2. Remove any Simple Modifications targeting the mouse. They run first and rewrite buttons out from under these rules.
3. Assign the side buttons in 8BitDo's Ultimate Software V2 to F16–F19. This is the step that wakes Buttons 6 and 7, and skipping it leaves them dead permanently.
4. Paste the rules into Karabiner-Elements → Complex Modifications, clearing the default contents first.

The files

• builder.html Assembles the rule set from your choices. Offline, no dependencies.
• README Setup and the button map.
• NOTES The lab notebook: what the hardware sends, what it refuses to send, and why every rule is shaped the way it is.
• RECIPES Around fifty ready-to-paste actions, plus a worksheet covering every input the mouse offers.
• INDEX A map of the whole repository.
• retro-r8-macmap.json The rule set itself. Seven manipulators.
• Retro-R8-Mouse-manual.pdf 8BitDo's booklet, for the button diagram and the hand-mode chords.

Two things worth knowing first