# Docs

Open the Trickpad menu in the menu bar. Click Edit Settings… to open the file, or click Manage with Agent to open it with an installed agent. The settings live in ~/.config/trickpad/config.toml, an easy-to-edit text file.

## Configuration

Trickpad uses TOML. Sections set what the lines below them apply to. Add blank lines, comments, and headings wherever they help you read the file.

Save the file, then choose Reload Settings. Invalid TOML rejects the reload. Unknown settings and gestures are skipped and reported.

### Example file

```toml
[GENERAL]
config-version = 3
haptic-feedback = true

[MOUSE]
hold-left-tap-right = "return"
hold-right-tap-left = "escape"
two-finger-tap = { action = "middle-click", defer = true }

[TRACKPAD]
hold-left-tap-right = "return"
hold-right-tap-left = "escape"
```

From Trickpad’s menu, you can see your current gestures, edit or reload settings, or open the file with an installed agent.

### File structure

| Section | Applies to |
| --- | --- |
| [GENERAL] | Settings that apply to the whole app. |
| [MOUSE] | Bindings for Magic Mouse. |
| [TRACKPAD] | Bindings for Magic Trackpad. |
| [MOUSE."Application"] | Bindings for one app when it is active. |
| [TRACKPAD."Application"] | Bindings for one app when it is active. |

### Comments and organization

A # starts a comment outside a quoted string. Comment out a binding to disable it without deleting it. Use comments to label groups, explain a choice, or leave a reminder. Keep the sections and bindings in any order that makes the file easy to scan.

```toml
# Voice input
[TRACKPAD]
three-finger-tap = "ctrl+cmd+a"
# hold-left-tap-right = "return"  # Temporarily disabled
```

### Application-specific bindings

Put an app name or exact bundle identifier in quotes after the device name. The app section overrides the global binding for the same gesture. Use "off" to exclude a global binding. TOML tables cannot repeat, so keep an app’s bindings together under its one device heading.

```toml
[TRACKPAD."Final Cut Pro"]
three-finger-tap = "space"

[TRACKPAD."com.apple.FinalCut"]
three-finger-swipe-left = "off"
```

### General settings

| Setting | Meaning |
| --- | --- |
| config-version | The configuration format, currently 3. During alpha, omitting it means the current format. |
| enable-mouse | true or false. Enables Magic Mouse bindings. Default: true. |
| enable-trackpad | true or false. Enables trackpad bindings. Default: true. |
| dominant-hand | left or right. Mirrors positional recognition for left-handed use. Default: right. |
| tap-speed | A positive number of seconds a tap may last. Default: 0.25. |
| haptic-feedback | true or false. Requests confirmation for configured trackpad gestures. Default: true. |
| experimental-mouse-click-gestures | true or false. Enables posture-sensitive Magic Mouse physical-click bindings. Default: false. |
| verbose-logging | true or false. Logs every gesture and keystroke to Console. Default: false. |

### Binding values

| Value | Syntax |
| --- | --- |
| Keystroke | Modifiers plus one key, such as cmd+shift+a. Use left- or right- prefixes when an app distinguishes modifier sides. |
| Built-in action | One of middle-click, mission-control, next-tab, previous-tab, new-tab, close-tab, reopen-tab, maximize, or minimize. |
| URL binding | An absolute URL prefixed with url:. This includes web URLs and app deep links such as raycast://, obsidian://, and things://. |
| Executable script | An executable path prefixed with script:. The path may begin with ~ or be absolute. |

### Binding options

| Option | Meaning |
| --- | --- |
| action | The binding value. Required in a global binding; an app-specific binding may omit it to inherit the global action. |
| defer | true or false. Waits through the Mac’s double-click interval before sending a tap action. Valid only for tap gestures. |
| haptic | true or false. Overrides haptic-feedback for one trackpad binding. Valid only for trackpad bindings. |

```toml
three-finger-tap = {
  action = "ctrl+cmd+a",
  defer = true,
  haptic = false
}
```

### URL substitutions

| Write this | Resolved value |
| --- | --- |
| {{clipboard}} | Clipboard text unchanged. |
| {{clipboard\|urlencode}} | Clipboard text encoded as one URL component. |
| {{datetime:FORMAT}} | The current local date and time in the given Apple date format. |

## Gesture reference

Add a gesture name to [MOUSE] or [TRACKPAD]. Use an application section for a different binding in one app.

### Magic Mouse and trackpads

- `hold-left-tap-right`: Hold one finger still, then tap another to its right
- `hold-right-tap-left`: Hold one finger still, then tap another to its left
- `two-finger-tap`: Tap with two fingers at the same time.
- `three-finger-tap`: Tap with three fingers at the same time.
- `three-finger-swipe-left`: Swipe left with three fingers.
- `three-finger-swipe-right`: Swipe right with three fingers.
- `three-finger-swipe-up`: Swipe up with three fingers.
- `three-finger-swipe-down`: Swipe down with three fingers.

### Magic Mouse additions

- `one-finger-tap`: Tap with one finger.
- `front-right-tap`: Tap the front-right area of the mouse.
- `one-finger-swipe-left`: Swipe left with one finger.
- `one-finger-swipe-right`: Swipe right with one finger.
- `two-finger-swipe-left`: Swipe left with two fingers.
- `two-finger-swipe-right`: Swipe right with two fingers.

### Built-in and Magic Trackpad additions

- `hold-slide`: Hold one finger still while sliding another.
- `four-finger-tap`: Tap with four fingers at the same time.
- `five-finger-tap`: Tap with five fingers at the same time.
- `three-finger-click`: Click with three fingers.
- `four-finger-click`: Click with four fingers.
- `four-finger-swipe-left`: Swipe left with four fingers.
- `four-finger-swipe-right`: Swipe right with four fingers.
- `four-finger-swipe-up`: Swipe up with four fingers.
- `four-finger-swipe-down`: Swipe down with four fingers.

[Read the product page](/trickpad/) for examples and FAQs.