Trickpad docs

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

~/.config/trickpad/config.tomlDefault

[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.

# 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.

[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.

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-rightHold one finger still, then tap another to its right
hold-right-tap-leftHold one finger still, then tap another to its left
two-finger-tapTap with two fingers at the same time.
three-finger-tapTap with three fingers at the same time.
three-finger-swipe-leftSwipe left with three fingers.
three-finger-swipe-rightSwipe right with three fingers.
three-finger-swipe-upSwipe up with three fingers.
three-finger-swipe-downSwipe down with three fingers.

Magic Mouse additions

one-finger-tapTap with one finger.
front-right-tapTap the front-right area of the mouse.
one-finger-swipe-leftSwipe left with one finger.
one-finger-swipe-rightSwipe right with one finger.
two-finger-swipe-leftSwipe left with two fingers.
two-finger-swipe-rightSwipe right with two fingers.

Built-in and Magic Trackpad additions

hold-slideHold one finger still while sliding another.
four-finger-tapTap with four fingers at the same time.
five-finger-tapTap with five fingers at the same time.
three-finger-clickClick with three fingers.
four-finger-clickClick with four fingers.
four-finger-swipe-leftSwipe left with four fingers.
four-finger-swipe-rightSwipe right with four fingers.
four-finger-swipe-upSwipe up with four fingers.
four-finger-swipe-downSwipe down with four fingers.

Read the product page for examples and FAQs.