Setup Process:

1. Create new trigger
2. Click “Conditional Activation” tab
3. Select condition type
4. Configure specific condition
5. Set default action + conditional overrides

Snap Zone Configuration

Multi-Monitor Snapping

Behavior Options:
- Snap to current screen only
- Allow snap across screens
- Define separate snap zones per monitor
- Mirror snap configuration on all monitors

Custom Snap Zones

Define custom snap areas beyond standard halves/quarters:

• Create snap zone by percentage (e.g., 30% left, 70% right)
• Position snap zones at specific coordinates
• Configure separate zones per screen
• Name zones for reference (“Code Editor Zone”)
• Test snap targets in preview mode

Touch Bar Elements

Widget Types

• System widgets (time, date, battery, volume)
• Custom HTML/CSS widgets
• Live app data (Mail unread count, Calendar)
• RSS feed display
• Stock ticker
• Weather widget
• System stats (CPU, memory, network)

App-Specific Bars

Configure different Touch Bar layout per application:

• Safari: back/forward, search, favorites
• Mail: compose, reply, archive buttons
• Finder: new folder, organize, preview buttons
• Code editor: build, debug, format buttons

Scripting Languages Supported

AppleScript Integration

tell application "BetterTouchTool"
  trigger_named "MyTriggerName"
  get_string_variable "myVar"
  set_string_variable "myVar" to "newValue"
end tell

JavaScript Conditions

// Check if Safari is frontmost
returnValue = frontApp === "com.apple.Safari";

// Device detection
returnValue = deviceType === "MacBook";

// Brightness level
returnValue = brightness > 50;

Shell Script Actions

#!/bin/bash
# Examples of shell commands in BTT
open -a "Visual Studio Code"
echo "Hello, World!" | pbcopy
defaults read com.apple.dock autohide

Sequence Example

1. Check if Slack is open (condition)
2. If yes: Get focus with ⌘1
3. If no: Launch Slack
4. Wait 2 seconds (delay)
5. Send message (action)
6. Return to previous app (cleanup)

Variable Management

BTT Variables:
- String variables (text values)
- Number variables (integers, floats)
- Boolean variables (true/false)
- Local scope (trigger only)
- Global scope (accessible everywhere)

Persistence:
- Session (cleared on restart)
- Permanent (saved in BTT config)

Export Configuration

Steps:

1. BTT Preferences → Main tab
2. Click “Export Preset” button
3. Select triggers/gestures to include
4. Save as .bttpreset file
5. Share via cloud, email, or public repo

Export Options:

• Export all triggers
• Export by application
• Export specific gesture type
• Include Touch Bar customizations
• Include variable definitions

Import Presets

1. File menu → Import Preset
2. Select .bttpreset file
3. Choose merge or replace existing config
4. BTT restarts to apply preset
5. Review imported triggers in sidebar

Community Presets

Popular sources for BTT presets:

• Reddit: r/BetterTouchTool
• GitHub: btt preset repositories
• BTT Forum: Community shared configs
• Gumroad: Paid professional presets
• Personal: Custom export/backup

Preset Safety:

• Backup existing config before importing
• Review triggers before activating
• Test with limited scope first
• Update presets regularly for compatibility

Floating Menu Types

Webview HUD Configuration

<!-- Custom webview example -->
<div id="menu" style="padding: 10px;">
  <button onclick="exec('trigger_named', 'MyTrigger')">
    Action 1
  </button>
  <button onclick="triggerNamed('MyTrigger2')">
    Action 2
  </button>
</div>

JavaScript in Webviews

// Trigger named trigger from webview
await btt.call('trigger_named', { name: 'MyTrigger' });

// Get variable value
const val = await btt.get_string_variable('myVar');

// Set variable
await btt.set_string_variable('myVar', 'newValue');

// Execute AppleScript
await btt.run_applescript('tell app "Finder" to activate');

Styling Webview HUDs

• Custom CSS for appearance
• Dark/light mode support
• Responsive layout for different displays
• Icon integration (SF Symbols, emoji)
• Animation support
• Keyboard shortcuts within menu

Notch Bar Features

The Notch Bar appears around the MacBook Pro notch:

Notch Bar Configuration

Settings:
- Enable/disable Notch Bar
- Set background opacity
- Choose button spacing
- Configure menu reveal style
- Set auto-hide timeout
- Define app-specific layouts
- Customize icon appearance

Notch Bar Best Practices

• Keep active buttons minimal (notch space limited)
• Use expandable groups for menus
• Prefer icons over text labels
• Test on actual display to verify layout
• Consider switching to different config per app
• Hide less-used buttons to preserve space

Performance Optimization

Performance Monitoring:

• Check Activity Monitor for BTT CPU/memory usage
• Identify slow triggers causing lag
• Disable and test triggers incrementally
• Profile gesture recognition accuracy vs speed

Backup & Recovery

Backup Strategies:

Automatic Backup:
- BTT saves config daily
- iCloud backup available
- Version history: 30 days

Manual Backup:
1. Export Preset with all triggers
2. Save to external drive
3. Backup to cloud storage
4. Version naming: btt-config-2026-02-15

Recovery:

1. Preferences → Main tab
2. Click “Revert to Backup”
3. Select desired backup date
4. BTT restarts with old config

URL Scheme Integration

BTT URL Scheme Format:

btt://trigger_named?trigger_name=MyTrigger
btt://execute_named_trigger?trigger_name=MyTrigger
btt://set_string_variable?name=var&value=123
btt://get_string_variable?name=var

Use Cases:

• Trigger BTT from other apps
• Automation via webhooks
• Keyboard maestro integration
• External app control
• Scripting automation chains

Cross-App Automation

Integration Examples:

Gesture Fine-Tuning

Improve Recognition:

• Practice gestures consistently
• Adjust sensitivity in preferences
• Test on trackpad corners vs center
• Use distinctive gesture patterns
• Avoid similar-looking gestures
• Calibrate for your hand size

Debug Gestures:

• Enable gesture logging
• Check if gesture triggered
• Verify action was executed
• Review conditional activation rules
• Test with simpler gesture first

Advanced Scripting Patterns

Pattern: Conditional Multi-Action

// Check app, then execute different actions
if (frontApp === "com.apple.Safari") {
  // Safari-specific action
  trigger_named("SafariAction");
} else if (frontApp === "com.microsoft.VSCode") {
  // Code editor action
  trigger_named("CodeAction");
} else {
  // Default action
  trigger_named("DefaultAction");
}

Pattern: Rate-Limited Trigger

// Prevent trigger spam
const lastTrigger = get_string_variable("lastTriggerTime");
const now = Date.now();
if (now - parseInt(lastTrigger) > 1000) {
  set_string_variable("lastTriggerTime", now.toString());
  returnValue = true; // Allow trigger
} else {
  returnValue = false; // Debounce
}

Hidden Features & Tricks

• Hold Option while dragging trigger to duplicate
• Right-click trigger name to show in Finder
• ⌘K in config window to search triggers
• Double-click trigger to quick edit name
• Drag triggers between apps to rearrange
• Option+scroll to zoom BTT UI
• ⌘D to duplicate selected trigger
• ⌘Delete to remove trigger instantly

Troubleshooting Common Issues

System Requirements & Compatibility

Supported:
- macOS 10.12+
- Apple Silicon & Intel Macs
- Multiple monitors
- Touch Bar (2016+)
- Notch bar (MacBook Pro 14"/16" 2021+)

Permissions Required:
- Accessibility (Input monitoring)
- Keyboard input (Key simulation)
- Screen recording (Gesture detection)
- Full disk access (File operations)

Note: These shortcuts are default configurations and may vary based on personal settings.

TipTap Actions: TipTap enables pressure-based single-finger taps on trackpad. Common configurations include opening BTT menu, launching apps, or triggering automations.

Configuration Tips:

• Most shortcuts are customizable through Preferences
• Long-press on triggers to reveal context menu options
• Use sidebar search to quickly find specific triggers

Named Triggers are custom-named actions that can be invoked from keyboard shortcuts, scripts, or other triggers.

Example Named Triggers:

• Screenshot to clipboard
• Open development tools in browser
• Toggle specific app window
• Execute multi-step automation sequence

Clipboard Features:

• View last 100+ clipboard items
• Search clipboard history
• Pin frequently used items
• Auto-clear old history
• Sync across devices (iCloud)

Window Switching Tips:

• Configure app-specific window cycling
• Use named triggers to focus specific windows
• Combine with window snapping for workflow efficiency

BetterTouchTool supports drawing custom gestures and special trackpad interactions:

Custom Gesture Setup:

1. Open BTT Preferences
2. Select “Trackpad” trigger type
3. Choose gesture drawing option
4. Draw gesture pattern on trackpad
5. Assign action to gesture
6. Practice gesture for reliable recognition