BetterTouchTool Trigger JSON Reference
This document provides a comprehensive reference for creating trigger configurations in BetterTouchTool using JSON.
Basic Trigger Structure
Every trigger must have these required fields:
{
"BTTTriggerType": 123,
"BTTTriggerClass": "BTTTriggerTypeKeyboardShortcut",
"BTTActionsToExecute": [
{
"BTTPredefinedActionType": 45
}
]
}
Required Fields
| Field | Type | Description |
|---|---|---|
BTTTriggerType |
Number | The specific trigger ID (see trigger types below) |
BTTTriggerClass |
String | The trigger category (must match the trigger type) |
Common Optional Fields
| Field | Type | Description | Default |
|---|---|---|---|
BTTUUID |
String | Unique identifier | Auto-generated |
BTTTriggerTypeDescription |
String | User-visible name/description | Auto-generated |
BTTEnabled |
Number | Enable/disable trigger (0 or 1) | 1 |
BTTEnabled2 |
Number | Secondary enabled state | 1 |
BTTOrder |
Number | Sort order in list | Auto |
BTTActionsToExecute |
Array | Actions to perform | [] |
Trigger Categories
1. Trackpad Gestures
BTTTriggerClass Options:
"BTTTriggerTypeTouchpadAll"- All trackpads"BTTTriggerTypeTouchpadBuiltIn"- Built-in only"BTTTriggerTypeTouchpadMagicTrackpad"- Magic Trackpad 1"BTTTriggerTypeTouchpadMagicTrackpad2"- Magic Trackpad 2"BTTTriggerTypeTouchBarTrackpad"- Touch Bar surface
Zero Finger Gestures
214- Release Last Finger Regardless of How Many Were Touching Before209- Release Last Finger After Previous Touch With 1 Finger210- Release Last Finger After Previous Touch With 2 Fingers211- Release Last Finger After Previous Touch With 3 Fingers212- Release Last Finger After Previous Touch With 4 Fingers213- Release Last Finger After Previous Touch With 5 Fingers
Single Finger Gestures
215- 1 Finger Touch Start157- Corner Click Bottom Left158- Corner Click Bottom Right182- Corner Click Top Left183- Corner Click Top Right184- Corner Force Click Top Left185- Corner Force Click Top Right186- Corner Force Click Bottom Left187- Corner Force Click Bottom Right207- 1 Finger Tap208- 1 Finger Double Tap203- Single Finger Force Click100- 1 Finger Tap Left Side101- 1 Finger Tap Right Side102- 1 Finger Tap Bottom103- 1 Finger Tap Top104- 1 Finger Tap Left Side Middle105- 1 Finger Tap Right Side Middle106- 1 Finger Tap Upper Left107- 1 Finger Tap Upper Right108- 1 Finger Tap Bottom Left109- 1 Finger Tap Bottom Right
Two Finger Gestures
216- 2 Finger Touch Start173- 2 Finger Tap179- 2 Finger Double-Tap174- 2 Finger Click175- 2 Finger Force Click176- 2 Finger Click (Left Finger Harder)177- 2 Finger Click (Right Finger Harder)178- 2 Finger Click (Both Fingers Same)180- 2 Finger Force Click (Left Finger Harder)181- 2 Finger Force Click (Right Finger Harder)159- 2 Finger Swipe Left160- 2 Finger Swipe Right161- 2 Finger Swipe Up162- 2 Finger Swipe Down165- 2 Finger Swipe From Left Edge166- 2 Finger Swipe From Right Edge167- 2 Finger Swipe From Top Edge168- 2 Finger Swipe From Bottom Edge121- 2 Finger Pinch In122- 2 Finger Pinch Out138- TipTap Middle (2 Fingers Fix)132- TipTap Left (2 Fingers Fix)133- TipTap Right (2 Fingers Fix)142- TipSwipe Left Finger Down (2 Fingers Fix)143- TipSwipe Left Finger Up (2 Fingers Fix)145- TipSwipe Left Finger Right (2 Fingers Fix)146- TipSwipe Left Finger Left (2 Fingers Fix)
Three Finger Gestures
217- 3 Finger Touch Start110- 3 Finger Tap163- 3 Finger Double-Tap111- 3 Finger Click170- 3 Finger Force Click181- 3 Finger Click & Hold188- 3 Finger Click (Left Finger Harder)189- 3 Finger Click (Middle Finger Harder)190- 3 Finger Click (Right Finger Harder)191- 3 Finger Force Click (Left Finger Harder)192- 3 Finger Force Click (Middle Finger Harder)193- 3 Finger Force Click (Right Finger Harder)112- 3 Finger Swipe Up113- 3 Finger Swipe Down114- 3 Finger Swipe Left115- 3 Finger Swipe Right197- 3 Finger Pinch In198- 3 Finger Pinch Out139- 3 Finger Tap Bottom140- 3 Finger Tap Top152- 3 Finger Dragging153- 3 Finger Clickswipe Left154- 3 Finger Clickswipe Right155- 3 Finger Clickswipe Up156- 3 Finger Clickswipe Down136- TipTap Left (3 Fingers Fix)137- TipTap Right (3 Fingers Fix)147- Triangle Swipe Top Left Corner148- Triangle Swipe Top Right Corner149- Triangle Swipe Bottom Left Corner150- Triangle Swipe Bottom Right Corner204- 3 Finger Drawing
Four Finger Gestures
218- 4 Finger Touch Start116- 4 Finger Tap169- 4 Finger Double Tap117- 4 Finger Click171- 4 Finger Force Click182- 4 Finger Click & Hold123- 4 Finger Swipe Up124- 4 Finger Swipe Down125- 4 Finger Swipe Left126- 4 Finger Swipe Right194- 4 Finger Pinch In195- 4 Finger Pinch Out205- 4 Finger Drawing
Five And More Finger Gestures
219- 5 Finger Touch Start119- 5 Finger Tap141- 5 Finger Click172- 5 Finger Force Click130- 5 Finger Swipe Down131- 5 Finger Swipe Up128- 5 Finger Swipe Left129- 5 Finger Swipe Right200- 5 Finger Pinch In201- 5 Finger Pinch Out206- 5 Finger Drawing151- 5 Finger Touch/Move199- 11 Finger Tap / Whole Hand
Your Own Gestures
164- Custom Tap Sequence (4 Fingers)220- First Touch With X Fingers, Then Release Y Fingers
2. Magic Mouse
BTTTriggerClass: "BTTTriggerTypeMagicMouse"
Zero Finger Gestures
51- Release Last Finger Regardless of How Many Were Touching Before52- Release Last Finger After Previous Touch With 1 Finger53- Release Last Finger After Previous Touch With 2 Fingers54- Release Last Finger After Previous Touch With 3 Fingers55- Release Last Finger After Previous Touch With 4 Fingers56- Release Last Finger After Previous Touch With 5 Fingers
Single Finger Gestures
50- 1 Finger Touch Start1- 1 Finger Tap2- 1 Finger Tap Left3- 1 Finger Tap Right23- 1 Finger Middle Click24- 1 Finger Tap Middle32- 1 Finger Tap Above Apple18- Scroll Up (modifier key needed)19- Scroll Down (modifier key needed)33- 1 Finger Swipe Down34- 1 Finger Swipe Up35- 1 Finger Swipe Left36- 1 Finger Swipe Right
Two Finger Gestures
57- 2 Finger Touch Start4- 2 Finger Tap62- 2 Finger Double-Tap20- 2 Finger Click7- 2 Finger Swipe Up8- 2 Finger Swipe Down5- 2 Finger Swipe Left6- 2 Finger Swipe Right14- Pinch In15- Pinch Out16- TipTap Left (1 Finger Fix)17- TipTap Right (1 Finger Fix)
Three Finger Gestures
58- 3 Finger Touch Start9- 3 Finger Tap63- 3 Finger Double-Tap21- 3 Finger Click13- 3 Finger Swipe Up12- 3 Finger Swipe Down10- 3 Finger Swipe Left11- 3 Finger Swipe Right30- TipTap Left (2 Fingers Fix)37- TipTap Middle (2 Fingers Fix)31- TipTap Right (2 Fingers Fix)60- TipSwipe Left Finger Up61- TipSwipe Left Finger Down
Four Finger Gestures
59- 4 Finger Touch Start25- 4 Finger Click27- 4 Finger Swipe Up26- 4 Finger Swipe Down28- 4 Finger Swipe Left29- 4 Finger Swipe Right
Moving, Resizing and Custom Drawings
40- 1 Finger Touch Top38- 2 Finger Touch Top39- 3 Finger Touch Top
3. Other Triggers / Automations
BTTTriggerClass: "BTTTriggerTypeOtherTriggers"
Named Trigger / Reusable Trigger Reference
643- Reusable Named Trigger
{
"BTTTriggerType": 643,
"BTTTriggerClass": "BTTTriggerTypeOtherTriggers",
"BTTTriggerName": "my_custom_trigger",
"BTTNamedTriggerAIDescription": "Trigger for opening Safari",
"BTTNamedTriggerAIAllow": 1,
"BTTActionsToExecute": [{
"BTTPredefinedActionType": 49
}]
}
General
685- BTT Mobile App Did Connect686- BTT Mobile App Did Disconnect689- Key Remap688- User Notification Did Show697- File Did Change698- Text Selection Did Change699- Script Output Changed700- Advanced Trigger Condition Changed701- Conditional Activation Group Activated702- Conditional Activation Group Deactivated694- Variable Value Changed691- Dock Icon696- Finder Context Menu Extension703- Battery Below X%704- Battery Above X%705- Battery Connected To AC706- Battery Running On Battery695- Did Open URL715- Clipboard Transformer641- Launch on Machine with Serial Number687- App Did Change (Focus)131- App Did Launch132- App Did Terminate133- App Did Activate134- App Did Deactivate693- Focused Window Did Change713- Focused Window Or Window Title Did Change690- Receive Workspace Notification692- Input Source Changed605- Before Mac Goes To Sleep606- After Mac Wakes From Sleep607- Received Distributed Notification With Name707- Did Open Lid708- Did Close Lid681- Did Connect To WiFi With Name682- Did Disconnect From WiFi With Name683- Screen Did Connect684- Screen Did Disconnect709- Did Start Screen Saver710- Did Stop Screen Saver711- Did Lock Screen712- Did Unlock Screen714- Dynamic JS Variable716- Ambient Light Goes Below717- Ambient Light Goes Above718- Ambient Light Abrupt Change By719- Clipboard Contents Changed
Window Buttons & Click Actions
613- Doubleclick Mac Menubar600- Doubleclick Window Titlebar623- Leftclick Full Screen Button614- Rightclick Full Screen Button627- Other Click Fullscreen Window Button622- Leftclick Red Window Button621- Leftclick Orange Window Button615- Leftclick Green Window Button601- Rightclick Red Window Button602- Rightclick Orange Window Button603- Rightclick Green Window Button626- Other Click Red Window Button625- Other Click Orange Window Button628- Other Click Green Window Button
Notch
649- Click Notch650- Double Click Notch651- Right Click Notch652- Move Mouse To Notch653- Move Mouse Away From Notch654- Move Mouse Away From Notch And From Menubar
Screen Corners / Edges
609- Top Left Corner610- Top Right Corner611- Bottom Left Corner612- Bottom Right Corner659- Mouse To Left Screen Edge660- Mouse To Right Screen Edge661- Mouse To Bottom Screen Edge662- Mouse To Top Screen Edge655- Mouse Away From Top Left Corner656- Mouse Away Top Right Corner657- Mouse Away Bottom Left Corner658- Mouse Away Bottom Right Corner663- Mouse Away From Left Screen Edge664- Mouse Away From Right Screen Edge665- Mouse Away From Bottom Screen Edge666- Mouse Away From Top Screen Edge
USB & Bluetooth LE
672- USB Device Did Connect673- USB Device Did Disconnect679- Bluetooth Device Did Connect680- Bluetooth Device Did Disconnect617- BT LE Go Away616- BT LE Come Close618- BT LE Out Of Range619- BT LE In Range Again
Time Based Triggers
678- Date/Time Based (Repeating)
{
"BTTTriggerType": 678,
"BTTTriggerClass": "BTTTriggerTypeOtherTriggers",
"BTTAdditionalConfiguration": "{\"BTTTimedRepeatEveryXSeconds\":\"0 0 * * * *\"}",
"BTTActionsToExecute": [{
"BTTPredefinedActionType": 153
}]
}
Custom Menu Bar Icons
667- Menu Bar Icon668- Menu Bar Icon (AppleScript)669- Menu Bar Icon (Shell Script)670- Always Hidden Status Item
4. Keyboard Shortcuts
BTTTriggerClass: "BTTTriggerTypeKeyboardShortcut"
{
"BTTTriggerType": 0,
"BTTTriggerClass": "BTTTriggerTypeKeyboardShortcut",
"BTTShortcutKeyCode": 49,
"BTTShortcutModifierKeys": 1048576,
"BTTActionsToExecute": [{
"BTTPredefinedActionType": 45
}]
}
Properties
| Property | Type | Description |
|---|---|---|
BTTShortcutKeyCode |
Number | Key code value |
BTTShortcutModifierKeys |
Number | Modifier key flags |
BTTLayoutIndependentChar |
String | Layout-independent character |
BTTAutoAdaptToKeyboardLayout |
Number | Auto-adapt to keyboard layout (0/1) |
BTTShortcutScope |
Number | Where shortcut is active |
BTTKeyboardShortcutMinTime |
Number | Minimum hold time |
BTTKeyboardShortcutMaxTime |
Number | Maximum hold time |
5. Key Sequences / Typed Words
BTTTriggerClass: "BTTTriggerTypeKeySequence"
Key sequences use trigger type 624.
6. Drawings
BTTTriggerClass: "BTTTriggerTypeDrawings"
Drawings use trigger type 620.
{
"BTTTriggerType": 620,
"BTTTriggerClass": "BTTTriggerTypeDrawings",
"BTTTriggerConfig": {
"BTTDrawingName": "My Gesture"
},
"BTTActionsToExecute": [{
"BTTPredefinedActionType": 45
}]
}
7. Mouse
BTTTriggerClass: "BTTTriggerTypeMouse"
Note: Regular mouse buttons (left, right, middle click) are configured differently and don't use trigger types in the same way.
8. Siri Remote
BTTTriggerClass: "BTTTriggerTypeSiriRemote"
Siri Remote Buttons
320- Volume Up321- Volume Down322- Siri323- Play/Pause324- TV/Screen325- Menu332- Volume Up Hold333- Volume Down Hold334- Siri Hold335- Play/Pause Hold336- TV/Screen Hold337- Menu Hold
Siri Remote Touchpad
326- Touchpad Click338- Touchpad Click Hold327- Touchpad Swipe Left328- Touchpad Swipe Right329- Touchpad Swipe Up330- Touchpad Swipe Down331- Touchpad Tap339- Touchpad Click Left340- Touchpad Click Right341- Touchpad Click Top342- Touchpad Click Bottom343- Touchpad Tap Left344- Touchpad Tap Right345- Touchpad Tap Top346- Touchpad Tap Bottom347- Touchpad Click Hold Left348- Touchpad Click Hold Right349- Touchpad Click Hold Top350- Touchpad Click Hold Bottom
New Siri Remote 2 Buttons
351- Button Left352- Button Right353- Button Up354- Button Down355- Power356- Button Left Hold357- Button Right Hold358- Button Up Hold359- Button Down Hold360- Power Hold361- Mute362- Mute Hold
9. Touch Bar
BTTTriggerClass: "BTTTriggerTypeTouchBar"
{
"BTTTriggerType": 630,
"BTTTriggerClass": "BTTTriggerTypeTouchBar",
"BTTTouchBarButtonName": "My Button",
"BTTTriggerConfig": {
"BTTTouchBarButtonColor": "58.650002, 58.650002, 58.650002, 255.000000",
"BTTTouchBarFontColor": "255, 255, 255, 255",
"BTTTouchBarFontSize": 15
},
"BTTActionsToExecute": [{
"BTTPredefinedActionType": 45
}]
}
Touch Bar Configuration Properties (in BTTTriggerConfig)
| Property | Type | Description | Default |
|---|---|---|---|
BTTTouchBarButtonColor |
String | Background color (R,G,B,A) | "58.65, 58.65, 58.65, 255" |
BTTTouchBarFontColor |
String | Text color (R,G,B,A) | "255, 255, 255, 255" |
BTTTouchBarFontSize |
Number | Font size | 15 |
BTTTouchBarButtonWidth |
Number | Width in pixels | Auto |
BTTTouchBarButtonHeight |
Number | Height in pixels | 30 |
BTTTouchBarItemIconWidth |
Number | Icon width | 15 |
BTTTouchBarItemIconHeight |
Number | Icon height | 15 |
BTTTouchBarItemPadding |
Number | Internal padding | 0 |
BTTTouchBarOnlyShowIcon |
Number | Show icon only (0/1) | 0 |
10. Stream Deck
BTTTriggerClass: "BTTTriggerTypeStreamDeck"
Stream Deck configuration uses similar properties to Touch Bar but in BTTTriggerConfig.
11. Notch Bar
BTTTriggerClass: "BTTTriggerTypeNotchBar"
Notch Bar configuration uses similar properties to Touch Bar but in BTTTriggerConfig.
12. Floating Menu
BTTTriggerClass: "BTTTriggerTypeFloatingMenu"
800- Floating Menu827- Menu Item840- Slider Item852- Text Field Item853- Text Area Item871- Submenu872- Back Button873- Webview870- Status Items Widget874- iOS Trackpad Item875- Row Breaker876- Column Breaker
13. MIDI
BTTTriggerClass: "BTTTriggerTypeMIDI"
{
"BTTTriggerType": 650,
"BTTTriggerClass": "BTTTriggerTypeMIDI",
"BTTTriggerConfig": {
"BTTMidiTriggerDeviceName": "*"
},
"BTTActionsToExecute": [{
"BTTPredefinedActionType": 45
}]
}
14. Generic Device
BTTTriggerClass: "BTTTriggerTypeGenericDevice"
880- Generic Device Analyzer881- Generic Device Trigger
15. BTT Remote (Legacy)
BTTTriggerClass: "BTTTriggerTypeBTTRemote"
Legacy BTT Remote triggers are numbered from 300-362.
Special Configurations
Colors
Colors are specified as comma-separated RGBA values:
"255, 255, 255, 255" = White (fully opaque)
"0, 0, 0, 255" = Black (fully opaque)
"255, 0, 0, 128" = Red (50% transparent)
Modifier Keys
Modifier keys use bitwise flags:
- Command (⌘):
1048576 - Option (⌥):
524288 - Control (⌃):
262144 - Shift (⇧):
131072 - Function (fn):
8388608
Combine with bitwise OR:
- ⌘⇧:
1048576 | 131072 = 1179648
Icons
Icons can be specified as:
- Base64 encoded image data in
BTTIconData - SF Symbol names in
BTTTouchBarItemSFSymbolDefaultIcon - File paths for Stream Deck icons
Conditions
Advanced conditions use BTTTriggerConditionsData with base64 encoded predicates.
Complete Examples
Keyboard Shortcut with HUD
{
"BTTTriggerType": 0,
"BTTTriggerClass": "BTTTriggerTypeKeyboardShortcut",
"BTTShortcutKeyCode": 49,
"BTTShortcutModifierKeys": 1179648,
"BTTTriggerTypeDescription": "Open Terminal",
"BTTTriggerConfig": {
"BTTShowHUD": 1,
"BTTHUDText": "Terminal Opened",
"BTTHUDDetailText": "⌘⇧Space"
},
"BTTActionsToExecute": [{
"BTTPredefinedActionType": 49,
"BTTLaunchPath": "/System/Applications/Utilities/Terminal.app"
}]
}
Touch Bar Button with Icon
{
"BTTTriggerType": 630,
"BTTTriggerClass": "BTTTriggerTypeTouchBar",
"BTTTouchBarButtonName": "Safari",
"BTTTriggerConfig": {
"BTTTouchBarButtonColor": "75.323769, 75.323769, 75.323769, 255.000000",
"BTTTouchBarItemIconWidth": 22,
"BTTTouchBarItemIconHeight": 22,
"BTTTouchBarItemSFSymbolDefaultIcon": "safari"
},
"BTTActionsToExecute": [{
"BTTPredefinedActionType": 49,
"BTTLaunchPath": "/Applications/Safari.app"
}]
}
Time-Based Trigger (Every Hour)
{
"BTTTriggerType": 678,
"BTTTriggerClass": "BTTTriggerTypeOtherTriggers",
"BTTTriggerTypeDescription": "Hourly Reminder",
"BTTAdditionalConfiguration": "{\"BTTTimedRepeatEveryXSeconds\":\"0 0 * * * *\"}",
"BTTActionsToExecute": [{
"BTTPredefinedActionType": 172,
"BTTNotificationText": "Take a break!",
"BTTNotificationDetails": "You've been working for an hour"
}]
}
Trackpad Three Finger Swipe
{
"BTTTriggerType": 112,
"BTTTriggerClass": "BTTTriggerTypeTouchpadAll",
"BTTTriggerTypeDescription": "Switch to Next Desktop",
"BTTActionsToExecute": [{
"BTTPredefinedActionType": 2
}]
}
Tips
- Always include both
BTTTriggerTypeandBTTTriggerClass - Use
BTTTriggerConfigfor Touch Bar, Stream Deck, and Notch Bar properties - Use
BTTAdditionalConfigurationfor most other trigger-specific settings - Actions must be in the
BTTActionsToExecutearray - Test your JSON with BTT's import feature before deploying
- Use UUIDs to update existing triggers
- Omit optional fields to use defaults