Skip to main content

Razer Mouse Support

Current versions of BetterTouchTool can configure Razer mice natively, no Razer Synapse required. BTT talks to the mouse directly over its USB cable, its HyperSpeed wireless dongle, or a direct Bluetooth connection.

Unlike Logitech mice, Razer side buttons already show up as standard mouse buttons (4 / 5), so they work with BetterTouchTool's Normal Mouse triggers without any special setup. On top of that, BTT's Razer support adds on-device configuration: DPI & DPI stages, polling rate, lighting, battery readout, idle timeout, and on-device button remapping.

Hardware-validated models: Razer Basilisk V3, Basilisk V3 Pro, Basilisk V3 X HyperSpeed, Basilisk V3 35K, Basilisk V3 Pro 35K, Orochi V2. Most other Razer mice use the same protocol and are supported on a best-effort basis. If something doesn't work on your model, please report it on the community forum.

Setup​

Go to the "Normal Mouse" section in BetterTouchTool and add a "Razer Mouse Configuration" row (via the + button, under "Razer Mouse Setup"). If a Razer mouse is connected, BTT also suggests adding it automatically.

Select your mouse in the configuration row, then adjust the settings you want BTT to manage. Everything is written to the mouse's onboard memory (where the hardware supports it) and re-applied automatically whenever the mouse reconnects or the Mac wakes from sleep. You don't need to install Razer Synapse.

What you can configure​

  • DPI stages – the list of DPI values the mouse cycles through, plus which one is active. Supports independent X/Y DPI on the Basilisk V3 family.
  • Polling rate – 125 / 500 / 1000 Hz (USB / dongle only — see below).
  • Lighting – static color, spectrum cycle, breathing, wave, or off, with brightness. Applies to all lighting zones (scroll wheel, logo, underglow).
  • Wireless idle timeout – how long before the mouse sleeps.
  • Low battery threshold (USB / dongle only).
  • Battery level – shown live in the configuration row for wireless mice.

Button remapping​

BetterTouchTool can rewrite a button's binding on the mouse itself. Because the remap is stored in the mouse's onboard memory, it keeps working even when BTT isn't running.

The configuration row's Button Remapping section lets you reassign the DPI button, thumb / HyperShift button, back / forward / middle buttons, scroll, and (on full-size Basilisk V3 models) the sensitivity clutch and wheel-tilt buttons.

The thumb / HyperShift button​

The dedicated thumb button (the one Razer uses for HyperShift) is fully remappable in BetterTouchTool. You can turn it into a BTT trigger (see below), a keyboard key or a mouse action, or leave it as the HyperShift modifier. Pick Thumb Button (HyperShift) in the Button Remapping section, choose what it should do, then press Apply To Mouse Now.

To restore the factory setting, choose "Restore Factory Default", which assigns HyperShift to the button again. If you want the HyperShift layer on a different button, you can also assign the HyperShift modifier to other buttons using the same dropdown.

HyperShift as a trigger

BTT reacts to the button after the mouse's firmware handles it. If you remap the thumb button to a key (e.g. F13), it becomes a normal BTT trigger, but it no longer acts as the HyperShift modifier. Each button can do one or the other, not both.

Turning a mouse button into a BTT trigger​

Some Razer buttons — most notably the DPI button and the thumb / HyperShift button — are handled entirely inside the mouse's firmware and normally never reach macOS. To use one of them as a BetterTouchTool trigger:

  1. In the Button Remapping section, set the button to "Send F13" (F13–F20 are available).
  2. Press Apply To Mouse Now.
  3. Add a normal Keyboard Shortcut trigger in BTT and press the mouse button to record it — it registers as F13.

From then on, the button runs whatever actions you assign to the shortcut. Choose "Restore Factory Default" to give the button its original behavior back (for the thumb button that's HyperShift, for the DPI button that's DPI cycling).

macOS only recognizes F1–F20

F21–F24 exist on the hardware but macOS never turns them into key events, so BTT only offers F13–F20. That's eight distinct trigger keys to spread across your mouse buttons.

DPI Stage Changed trigger​

If you'd rather keep the DPI button cycling DPI, you can still react to it: add the "Razer Mouse DPI Stage Changed" trigger (in the "Automations & Named & Other Triggers" section, group "General"). It fires whenever a supported mouse announces a DPI change, and sets the variables razer_dpi, razer_dpi_stage and razer_device before running its actions.

Predefined actions​

In addition to the configuration row, the "Razer Mouse Actions" group offers these actions, which you can assign to any trigger. The group appears once a Razer mouse has been connected:

  • Razer Mouse: Set DPI
  • Razer Mouse: Cycle DPI Stage
  • Razer Mouse: Increase DPI / Razer Mouse: Decrease DPI
  • Razer Mouse: Set Polling Rate
  • Razer Mouse: Set Lighting

Bluetooth vs. USB / dongle​

A Razer mouse connected through its cable or HyperSpeed dongle supports the full feature set. Over a direct Bluetooth connection (e.g. Basilisk V3 X HyperSpeed, Basilisk V3 Pro), DPI stages, battery, lighting (static / spectrum / brightness / off), idle timeout, button remapping and the DPI-stage trigger all work. However, you can't adjust the polling rate or the low battery threshold, because the mouse's Bluetooth protocol doesn't expose them. BTT shows a note if you try to set something that isn't available on the current connection.

JavaScript API​

You can also script everything above from BetterTouchTool's JavaScript (Run Real JavaScript action, floating menu scripts, etc.):

let devices = await razer_get_devices();
let battery = await razer_get_battery({});
let dpi     = await razer_get_dpi({});
await razer_set_dpi({dpi: 1600});
await razer_set_dpi_stages({stages: [400, 800, 1600, 3200], activeStage: 2});
await razer_cycle_dpi_stage({direction: 1});
await razer_set_polling_rate({hz: 1000});
await razer_set_lighting({mode: "static", color: [0, 255, 0], brightness: 80});

// Remap a physical button on the mouse. slot 96 = DPI button, 0x39 = thumb button.
await razer_remap_button({slot: 96, target: "f13"});        // -> becomes a BTT trigger
await razer_remap_button({slot: 0x39, target: "f14"});      // thumb/HyperShift button -> trigger
await razer_remap_button({slot: 0x39, target: "hypershift"}); // restore HyperShift
await razer_remap_button({slot: 96, target: "default"});    // factory default

There are also razer_send_raw_request (USB) and razer_ble_send_raw_request (Bluetooth) for sending raw protocol commands. They're useful for validating models BTT hasn't been tested with. If you get something working on an untested mouse this way, please share it on the forum so it can be added.