mouse_motion_and_wheel_to_key
mouse_motion_and_wheel_to_key changes mouse cursor movement or scroll wheel input to key taps.
mouse_motion_and_wheel_to_key is available since Karabiner-Elements 16.3.9.
Enable your mouse
To use this configuration, you need to enable your mouse in the Devices tab.
{
"type": "mouse_motion_and_wheel_to_key",
"from": {
"source": "xy",
"modifiers": {
"mandatory": [...],
"optional": [...]
},
"threshold": 20,
"sampling_interval_milliseconds": 100,
"cooldown_milliseconds": 100
},
"to": {
"up": [...],
"down": [...],
"left": [...],
"right": [...]
},
"conditions": ...
}
| Key | Value | Required | Description |
|---|---|---|---|
type |
"mouse_motion_and_wheel_to_key" |
Required | — |
from.source |
"xy", "wheels", "horizontal_wheel", "vertical_wheel" |
Required | Select mouse cursor movement or wheel input. See Input sources below. |
from.modifiers |
Same as basic.from.modifiers | Optional | Enable the manipulator if specified modifiers are pressed |
from.threshold |
Number | Optional | Minimum accumulated input delta to emit a key tap. The default value is 20 for xy, or 1 for wheel sources. Units are input deltas, not pixels or scroll lines. |
from.sampling_interval_milliseconds |
Number | Optional | Sampling window duration in milliseconds. The default value is 100. |
from.cooldown_milliseconds |
Number | Optional | Time in milliseconds after an output event is emitted during which selected input is consumed without accumulation. The default value is 100. |
to |
An object mapping up, down, left, and right to output arrays |
Required | Each direction contains an array of output events. Directions you do not need can be omitted. |
conditions |
Same as basic.conditions | Optional | Enable the manipulator when specified conditions are met |
Caution
When using from.source: "xy", you should set either from.modifiers or conditions.
Without them, mouse cursor movement is always consumed, so you cannot move the cursor with that mouse.
Input sources
from.source |
Selected input | Output directions |
|---|---|---|
xy |
Both mouse cursor axes | up, down, left, right |
wheels |
Both scroll wheel axes | up, down, left, right |
horizontal_wheel |
Horizontal wheel (tilt) | left, right |
vertical_wheel |
Vertical wheel | up, down |
Direction names refer to input deltas before macOS scrolling preferences are applied.
| Input | to.left |
to.right |
to.up |
to.down |
|---|---|---|---|---|
| Mouse cursor | X < 0 | X > 0 | Y < 0 | Y > 0 |
| Scroll wheel | Horizontal < 0 | Horizontal > 0 | Vertical > 0 | Vertical < 0 |
Tuning tips
| Symptom | Adjustment |
|---|---|
| A single movement or tilt triggers repeated key presses | Increase from.cooldown_milliseconds. Try 500 (500 ms). |
| No response | Decrease from.threshold. Try 1. |
| The response is too slow | Decrease from.sampling_interval_milliseconds. Try 50 (50 ms). |
Examples
fn + mouse movement to control + arrow keys
The following JSON changes fn + mouse movement to control + arrow keys.
{
"description": "Change fn + mouse movement to control + arrow keys",
"manipulators": [
{
"type": "mouse_motion_and_wheel_to_key",
"from": {
"source": "xy",
"threshold": 20,
"sampling_interval_milliseconds": 100,
"cooldown_milliseconds": 100,
"modifiers": {
"mandatory": ["fn"],
"optional": ["any"]
}
},
"to": {
"up": [
{ "key_code": "up_arrow", "modifiers": ["left_control"] }
],
"down": [
{ "key_code": "down_arrow", "modifiers": ["left_control"] }
],
"left": [
{ "key_code": "left_arrow", "modifiers": ["left_control"] }
],
"right": [
{ "key_code": "right_arrow", "modifiers": ["left_control"] }
]
}
}
]
}
Wheel tilt to command + arrow keys
The following json changes horizontal wheel input (tilt) to command + left_arrow or command + right_arrow. Vertical scrolling, mouse cursor movement, and button clicks pass through unchanged.
{
"description": "Change wheel tilt to command + arrow keys",
"manipulators": [
{
"type": "mouse_motion_and_wheel_to_key",
"from": {
"source": "horizontal_wheel",
"threshold": 1,
"sampling_interval_milliseconds": 100,
"cooldown_milliseconds": 100,
"modifiers": { "optional": ["any"] }
},
"to": {
"left": [
{ "key_code": "left_arrow", "modifiers": ["left_command"] }
],
"right": [
{ "key_code": "right_arrow", "modifiers": ["left_command"] }
]
}
}
]
}