Scroll Modifiers
Scroll Modifiers (available since BetterTouchTool 5.780) let you change the scrolling behavior of any mouse or trackpad on the fly.
Set Up a Scroll Modifier:
To set up a scroll modifier, go to the "Normal Mouse" section in BetterTouchTool, add a new trigger with the + button and pick a modifier from the "Scroll Behavior Modifiers" group. You can configure each modifier with:
- Device Type Conditions: Apply the modifier only to specific devices ("Only Apply To Regular Mice", "Only Apply To Touch Devices (Trackpad + Magic Mouse)", "Only Apply To Magic Mouse", "Only Apply To Trackpad")
- Axis Conditions (for many modifiers): "Only Modify Horizontal Axis" / "Only Modify Vertical Axis"
- Modifier Key Conditions: Apply the modifier only when specific modifier keys are pressed (Shift, Control, Option, Command, Function)
Advanced trigger conditions are only checked once, at the start of a scroll.
You can set up multiple scroll modifiers, and they're chained automatically. For some combinations, the order in which they appear in the UI matters.
App Specific Scroll Modifiers
If you want some scroll modifiers to be active only in specific apps, don't add them at the "All Apps" level. Assign them to those specific apps instead.
If you want the scroll modifiers enabled in most apps but not in a few, use a Conditional Activation Group.
Detailed Scroll Modifier Description:
Smooth Scrolling (like Trackpad)
Adds trackpad-like smooth scrolling to mouse wheels using 60 FPS interpolation, so the step-by-step scrolling of a mouse wheel feels as smooth as a trackpad. New Smooth Scrolling modifiers have "Only Apply To Regular Mice" enabled.
Configurable Values:
| Parameter | Range | Default | Description |
|---|---|---|---|
| Vertical Speed | 0.1 - 10 | 3.0 | Speed multiplier for vertical scrolling |
| Horizontal Speed | 0.1 - 10 | 3.0 | Speed multiplier for horizontal scrolling |
| Smoothness | 0 - 3 | 0.5 | How smooth the scrolling feels. 0 = snappy/responsive, 1 = the previous maximum smoothing, values above 1 add extra smoothing |
| Fixed Distance Per Tick | 0 - 1 | 0 | Removes macOS's built-in scroll acceleration for normal mouse wheels. 0 = keep the system behavior, 1 = every wheel tick scrolls exactly the configured Distance Per Tick. Values in between blend the two |
| Distance Per Tick (px) | 1 - 100 | 8 | The distance one wheel tick should travel (before the speed multipliers are applied) |
| Acceleration Strength | 0 - 2 | 0 | Adds extra acceleration on top of the curve macOS already applies. 0 = BTT adds none |
| Simulate Trackpad Scrolling | On/Off | On | Emits trackpad phase events for apps that need them (Messages, Calendar, Safari) |
| Simulate Trackpad Scrolling Only For Horizontal Scrolls | On/Off | Off | Only emit the trackpad phase events for horizontal scrolling |
| Discrete Line Mode (for line-by-line selection) | On/Off | Off | Delivers small scroll ticks immediately without smoothing, preserving the "tick" nature needed for line-by-line item selection |
Acceleration Strength can't remove the system acceleration. For that, use Fixed Distance Per Tick or the separate "Disable / Reduce Scroll Acceleration" modifier (see below).
Vertical & Horizontal Scroll Speed Modifier
Multiplies scroll deltas by the specified values to speed up or slow down scrolling.
Configurable Values:
| Parameter | Range | Default | Description |
|---|---|---|---|
| Vertical Multiplier | any number | 1.0 | Multiplier for vertical scrolling |
| Horizontal Multiplier | any number | 1.0 | Multiplier for horizontal scrolling |
Value Guide:
- 1.0: No change (default)
- > 1.0: Faster scrolling (e.g., 2.0 = twice as fast)
- < 1.0: Slower scrolling (e.g., 0.5 = half speed)
- < 0: Reverses direction
Typical range: 0.1 to 5.0
Block Horizontal Scrolling
Completely suppresses left/right scrolling.
Use Cases:
- Preventing accidental horizontal scrolling in vertical-only content
- Applications where horizontal scroll causes unwanted behavior
- Mice with sensitive horizontal scroll wheels
No configurable values. It just blocks all horizontal scroll events.
Block Vertical Scrolling
Completely suppresses up/down scrolling.
Use Cases:
- Preventing accidental vertical scrolling in horizontal-only content
- Spreadsheet applications when editing horizontally
- Timeline or carousel interfaces
No configurable values. It just blocks all vertical scroll events.
Scroll Acceleration Curve
Applies an acceleration curve that makes fast scrolling even faster while keeping slow scrolling precise.
Formula: output = input × (1 + strength × √(|input|/4))
Configurable Values:
| Parameter | Range | Default | Description |
|---|---|---|---|
| Horizontal Strength | 0 - 2 | 1.0 | Acceleration strength for horizontal scrolling |
| Vertical Strength | 0 - 2 | 1.0 | Acceleration strength for vertical scrolling |
Value Guide:
- 0.0: No acceleration (linear)
- 1.0: Default macOS-like acceleration
- 2.0: Strong acceleration
Useful for large documents where you want quick navigation with fast scrolls but precise control with slow scrolls.
Reverse Scroll Direction
Inverts the scroll direction for the selected axes (natural vs traditional scrolling).
Configurable Values:
| Parameter | Options | Default | Description |
|---|---|---|---|
| Reverse Horizontal | On/Off | Off | Invert horizontal scroll direction |
| Reverse Vertical | On/Off | Off | Invert vertical scroll direction |
Use Cases:
- Switch between 'natural' and 'traditional' scrolling per device
- Invert only the horizontal or only the vertical axis
- Apply different scroll directions to mouse vs trackpad
Swap Scroll Axes (H ↔ V)
Exchanges horizontal and vertical scroll axes. Scrolling up/down becomes left/right and vice versa.
Use Cases:
- Horizontal scrolling with vertical-only scroll wheels
- Navigating timelines with a vertical scroll gesture
- Working with horizontally oriented content
No configurable values. It just swaps the axes.
Lock Scroll to Dominant Axis
Prevents diagonal scrolling by locking to the dominant axis. Scrolling can stay diagonal until the threshold is reached. Once one axis is clearly stronger than the other, scrolling stays on that axis for the rest of the gesture, including momentum, and the other axis stays blocked until a new gesture starts. For regular mouse wheels, a short pause starts a new gesture.
Configurable Values:
| Parameter | Range | Default | Description |
|---|---|---|---|
| Lock Threshold | 1 - 10 | 2.0 | Ratio threshold for locking |
Value Guide:
- 1.0: Locks on the first movement
- 2.0: Default - locks when one axis is at least 2× stronger than the other
- 5.0+: Requires stronger dominance before locking
Useful for precise vertical/horizontal scrolling in grids, lists, or code editors.
Scroll Dead Zone Filter
Ignores small scroll movements. Scroll events with a delta below the threshold are blocked entirely.
Configurable Values:
| Parameter | Range | Default | Description |
|---|---|---|---|
| Horizontal Dead Zone | 0 - 100 | 0 | Minimum horizontal delta (in pixels) |
| Vertical Dead Zone | 0 - 100 | 0 | Minimum vertical delta (in pixels) |
Value Guide:
- 0: No dead zone (all scrolling passes through)
- 1-5: Small dead zone for slight jitter
- 5-20: Medium dead zone for accidental touches
- 20+: Large dead zone for very deliberate scrolling only
Useful for sensitive mice or trackpads.
Scroll Event Debounce
Rate-limits scroll events by blocking events that occur too close together.
Configurable Values:
| Parameter | Range | Default | Description |
|---|---|---|---|
| Debounce Time | 0 - 1 | 0.05 | Minimum time (in seconds) between events |
Value Guide:
- 0.01-0.03: Minimal debounce for high-speed scrolling
- 0.05: Default - good balance
- 0.1-0.2: Slower, more deliberate scrolling
- 0.5+: Very slow, single-step scrolling
Useful for mice with jittery scroll wheels or when you want more controlled scrolling.
Clamp Maximum Scroll Speed
Limits the maximum scroll speed by capping delta values. Scroll deltas above the maximum are reduced to the maximum.
Configurable Values:
| Parameter | Range | Default | Description |
|---|---|---|---|
| Max Horizontal Delta | 0 - 1000 | 0 | Maximum horizontal delta (in pixels). 0 = unlimited |
| Max Vertical Delta | 0 - 1000 | 0 | Maximum vertical delta (in pixels). 0 = unlimited |
Value Guide:
- 0: No clamping (unlimited speed)
- 10-50: Light clamping for smoother scrolling
- 50-100: Moderate speed limit
- 100-500: Strong limit for precise control
Useful to keep scrolling from getting too fast in apps.
Scroll Distance Per Tick
Sets a fixed pixel distance per scroll tick for discrete scroll wheels.
Configurable Values:
| Parameter | Range | Default | Description |
|---|---|---|---|
| Horizontal Pixels Per Tick | 1 - 500 | 10 | Pixels scrolled per horizontal tick |
| Vertical Pixels Per Tick | 1 - 500 | 10 | Pixels scrolled per vertical tick |
Value Guide:
- 5-10: Fine scrolling, good for code editors
- 10-20: Default comfortable range
- 20-50: Faster page navigation
- 50-100: Large jumps per tick
Note: Only affects discrete (non-continuous) scrolling from mouse wheels. Continuous trackpad scrolling is not affected.
Smooth Zoom (Scroll to Magnify)
Listed in BTT as "Scroll Modifier: Zoom In / Out (like Trackpad)". Converts scroll wheel input into smooth pinch-to-zoom (magnification) gestures. Uses 60 FPS CVDisplayLink interpolation to transform discrete scroll events into fluid zoom gestures that work in apps like Safari, Maps, Photoshop, and Preview. Alternatively, it can zoom the whole screen using macOS Accessibility Zoom.
Configurable Values:
| Parameter | Range | Default | Description |
|---|---|---|---|
| Zoom target | App content / Screen (Accessibility Zoom) | App content | "App content" sends pinch-to-zoom gestures to the app. "Screen (Accessibility Zoom)" zooms the screen using macOS Accessibility Zoom (choose Full Screen in System Settings > Accessibility > Zoom to magnify the entire screen) |
| Sensitivity | 0.001 - 0.1 | 0.01 | Magnification amount per scroll pixel. Higher = faster zoom |
| Acceleration Factor | 0 - 5 | 2.1 | Velocity-based acceleration. 0 = constant speed, higher = faster scrolling increases zoom speed |
| Base Multiplier | 0.1 - 10 | 1.0 | Overall magnification multiplier |
| Max Magnification Per Frame | 0.01 - 2 | 0.5 | Maximum magnification per frame (prevents jumpy zooming) |
| Stop Threshold | 0.00001 - 0.1 | 0.0001 | Minimum magnification before output stops |
| Input Timeout (seconds) | 0.05 - 1 | 0.15 | Time before the gesture ends after scrolling stops |
| EMA Alpha (smoothing) | 0 - 1 | 0.3 | Smoothing factor for input. Lower = more smoothing |
| Duration | 0.1 - 0.5 | 0.15 | Interpolation speed (LERP coefficient). Lower = snappier, higher = smoother |
| Invert Zoom Direction | On/Off | Off | Invert zoom direction (scroll up = zoom out) |
| Use Horizontal Scroll Axis | On/Off | Off | Use horizontal scroll axis instead of vertical |
Use Cases:
- Zooming in maps with a regular mouse wheel
- Zooming images in Preview, Photoshop, or other image editors
- Zooming web pages in Safari or Chrome
- Any application that supports pinch-to-zoom gestures
How It Works: The modifier captures scroll events and converts them into synthetic magnification gesture events using CVDisplayLink for smooth 60 FPS interpolation. Velocity tracking adds natural acceleration: faster scrolling creates larger zoom changes, just like on a trackpad.
Smooth Rotate (Scroll to Rotation)
Listed in BTT as "Scroll Modifier: Rotate Left / Right (like Trackpad)". Converts scroll wheel input into smooth two-finger rotation gestures. Uses 60 FPS CVDisplayLink interpolation to transform discrete scroll events into fluid rotation gestures that work in apps like Preview, Photos, and image editors.
Configurable Values:
| Parameter | Range | Default | Description |
|---|---|---|---|
| Sensitivity (degrees/pixel) | 0.01 - 5 | 0.5 | Rotation degrees per scroll pixel. Higher = faster rotation |
| Acceleration Factor | 0 - 5 | 2.1 | Velocity-based acceleration. 0 = constant speed, higher = faster scrolling increases rotation speed |
| Base Multiplier | 0.1 - 10 | 1.0 | Overall rotation multiplier |
| Max Rotation Per Frame (degrees) | 1 - 90 | 15.0 | Maximum rotation degrees per frame (prevents jumpy rotation) |
| Stop Threshold (degrees) | 0.001 - 1 | 0.001 | Minimum rotation before output stops |
| Input Timeout (seconds) | 0.05 - 1 | 0.15 | Time before the gesture ends after scrolling stops |
| EMA Alpha (smoothing) | 0 - 1 | 0.3 | Smoothing factor for input. Lower = more smoothing |
| Invert Rotation Direction | On/Off | Off | Invert rotation direction |
| Use Horizontal Scroll Axis | On/Off | Off | Use horizontal scroll axis instead of vertical |
| Duration | 0.1 - 0.5 | 0.15 | Interpolation speed (LERP coefficient). Lower = snappier, higher = smoother |
Use Cases:
- Rotating images in Preview or image editors
- Rotating objects in 3D applications
- Any application that supports two-finger rotation gestures
How It Works: The modifier captures scroll events and converts them into synthetic rotation gesture events using CVDisplayLink for smooth 60 FPS interpolation. Velocity tracking adds natural acceleration: faster scrolling creates larger rotation changes, just like on a trackpad.
Smooth Space Switch (Scroll to Switch Spaces)
Listed in BTT as "Scroll Modifier: Space Switch Swipe (like Trackpad)". Converts scroll wheel input into smooth Mission Control space switching swipes. Uses 60 FPS CVDisplayLink interpolation to transform discrete scroll events into fluid space switching gestures, similar to a three-finger swipe on a trackpad.
Configurable Values:
| Parameter | Range | Default | Description |
|---|---|---|---|
| Sensitivity | 0.0005 - 0.01 | ~0.0017 (1/600) | How much scroll affects the swipe. Higher = faster space switching |
| Stop Threshold | 0.0001 - 0.1 | 0.001 | Minimum movement threshold before output stops |
| Input Timeout (seconds) | 0.05 - 1 | 0.2 | Time before the gesture ends after scrolling stops |
| Completion Threshold | 0.2 - 0.8 | 0.4 | How far to swipe before completing the space switch. Lower = easier to trigger |
| Duration (smoothing) | 0.05 - 0.5 | 0.2 | Interpolation speed (LERP coefficient). Lower = snappier, higher = smoother |
| Invert Swipe Direction | On/Off | Off | Invert swipe direction (scroll up = swipe right) |
| Use Horizontal Scroll Axis | On/Off | Off | Use horizontal scroll axis instead of vertical |
Use Cases:
- Switching between Mission Control Spaces/Desktops with a mouse scroll wheel
- Navigating virtual desktops without a trackpad
- Quick workspace navigation while keeping your hand on the mouse
How It Works: The modifier captures scroll events and converts them into synthetic dock swipe gesture events that macOS uses for space switching. It uses CVDisplayLink for smooth 60 FPS interpolation, providing a fluid preview animation as you scroll.
Key Behaviors:
- One space per gesture: Each scroll gesture switches at most one space, which prevents accidental multi-space jumps
- Automatic snap-back: If you don't scroll far enough to reach the completion threshold, the view snaps back to the original space
- Cooldown protection: After switching a space, there's a brief cooldown (0.8s) to prevent accidental double-switches. This cooldown resets if you pause scrolling for 0.3s
- Direction clamping: The swipe offset is clamped to prevent overshooting, ensuring predictable single-space switching
Tips:
- Lower the Completion Threshold if you want to switch spaces with less scrolling
- Increase Sensitivity for faster response to scroll input
- Use Invert Swipe Direction if the default direction feels backwards to you
- Works best with Only Apply To Regular Mice enabled (the default for new modifiers) to avoid conflicts with trackpad gestures
Ignore Events from Specific Apps
Listed in BTT as "Scroll Modifier: Ignore Events from Specific Apps". Scroll events pass through unmodified while the frontmost app matches one of the specified names.
Configurable Values:
| Parameter | Description |
|---|---|
| App Names / Bundle IDs (comma-separated) | App names (e.g. Safari), bundle identifiers (e.g. com.apple.Safari) or executable names. Matching is case-insensitive |
The position of this modifier in the scroll modifier list matters: all modifiers above it still apply, while modifiers below it are skipped for matching apps.
Disable / Reduce Scroll Acceleration
Listed in BTT as "Scroll Modifier: Disable / Reduce Scroll Acceleration". Removes or reduces macOS scroll acceleration to produce linear scrolling.
Configurable Values:
| Parameter | Range | Default | Description |
|---|---|---|---|
| Pixels Per Mouse Wheel Tick | 0 - 200 | 10 | Each mouse wheel tick scrolls this fixed number of pixels, replacing the accelerated system deltas. Apps that scroll by lines (e.g. Excel) receive the same distance converted at 10px = 1 line (at least 1 line per tick). Set to 0 to use the continuous curve below for mouse wheels too |
| Continuous Deceleration Strength | 0.1 - 1 | 0.5 | Exponent of the inverse power curve used for trackpads / Magic Mouse. Lower = removes more acceleration (0.5 = moderate, 0.4 = strong, 0.7 = mild) |
| Reference Speed (pivot point) | 1 - 100 | 10 | Speed where output equals input. Below it scrolling is mostly unchanged, above it fast scrolling is brought back down |
| Linear Zone (no deceleration below) | 0 - 20 | 1 | Small movements below this value are not modified |
| Output Speed Scale | 0.1 - 10 | 1 | Overall output speed multiplier |