Skip to main content

BetterTouchTool Floating Menu JSON Documentation

This document describes the JSON structure for creating floating menus in BetterTouchTool.

NOTE Some text is replaced with special characters to reduce the size of this document for LLM usage: © = BTT $ = BTTMenu § = BTTMenuItem

Basic Structure​

A floating menu JSON is an array containing menu objects. Each menu can contain multiple menu items via the §s array.

[
  {
    "©TriggerType": 767,
    "©TriggerTypeDescriptionReadOnly": "Floating Menu",
    "©TriggerClass": "©TriggerTypeFloatingMenu",
    "©UUID": "unique-uuid-here",
    "©Enabled": 1,
    "©TriggerName": "Floating Menu: Menu Name",
    "$Name": "Menu Name",
    "$Config": { /* menu configuration */ },
    "§s": [ /* array of menu items */ ],
    "$Availability": 0  /* 0=everywhere, 1=mac, 2=ios */
  }
]
  • 767 - Menu (top level)
  • 773 - Standard Item (button with actions)
  • 774 - Submenu (contains nested items)
  • 775 - Slider
  • 776 - Text Field (value queryable via scripts)
  • 777 - Back Button (for submenus)
  • 778 - WebView (displays HTML from §Text)
  • 800 - Trackpad widget
  • 801 - Row Breaker
  • 802 - Column Breaker
  • 810 - Text Area (value queryable via scripts)
  • 811 - Floating Menu Reference

Core Properties​

  • ©TriggerType: 767 for menu
  • ©UUID: Unique identifier
  • ©Enabled: 1 to enable
  • $Name: Display name
  • $Config: Configuration object
  • §s: Array of menu items
  • $Availability: 0=everywhere, 1=mac, 2=ios, 3=iphone, 4=ipad
  • ©Order: Display order
  • ©LastUpdatedAt: Timestamp
  • ©AppBundleIdentifier: App-specific bundle ID
  • ©AppName: App-specific name

Item Properties​

  • ©TriggerType: Item type (773, 774, etc.)
  • ©TriggerParentUUID: Parent menu's UUID
  • ©UUID: Unique identifier
  • ©Enabled: 1 to enable
  • ©TriggerName: Display name
  • $Config: Item configuration
  • §Actions: Array of actions

Positioning & Layout​

  • $PositioningType: 0=freeMove, 1=fixedPosition, 2=menubarStatusItem
  • $PositionRelativeTo: 0=focusedWindow, 1=screenWithMouse, 3=focusedScreen, 7=mousePosition, 8=builtin, 11=notch, 12=focusedMenubar, 19=screenWithDock, 20=greenWindowButton, 21=hoveredFloatingMenuItem, 22=specificFloatingMenu, 23=dock
  • $AnchorMenu: 0=topLeft, 1=topRight, 2=bottomLeft, 3=bottomRight, 4=center, 5=topEdgeCenter, 6=rightEdgeCenter, 7=bottomEdgeCenter, 8=leftEdgeCenter
  • $AnchorRelation: Same values as $AnchorMenu
  • $OffsetX/$OffsetY: Position offset (positive X = right, negative X = left; positive Y = up, negative Y = down)
  • $OffsetXUnit/$OffsetYUnit: 0=absolute, 1=menu%, 2=referenceFrame%
  • $PositionDynamicVariable: Variable for dynamic positioning
  • $ScreenUUID: Specific screen UUID

Layout Direction​

  • $LayoutDirection: 0=fillRow, 1=fillColumn, 2=fillRowFixed, 3=fillColumnFixed, 4=absoluteScrollable, 5=absoluteFixed, 6=verticalOneColumn, 7=horizontalOneRow, 8=circular
  • $HorizontalAlignment: 0=leading, 1=center, 2=trailing
  • $VerticalAlignment: 0=top, 1=center, 2=bottom
  • $VerticalSpacing: Vertical spacing (pixels)
  • $HorizontalSpacing: Horizontal spacing (pixels)

Size​

  • $SizingBehavior: 0=zero, 1=fixed, 2=variable, 3=content
  • $FrameWidth/$FrameHeight: Menu dimensions
  • $FrameMaxWidth/$FrameMaxHeight: Maximum dimensions
  • $FrameWidthVariable/$FrameHeightVariable: Variable names for dynamic sizing

Hover Behavior​

  • $ResizeOnHover: 1 to enable hover resize
  • $SizingBehaviorHover: Hover sizing mode
  • $FrameWidthHovered/$FrameHeightHovered: Hovered dimensions
  • $FrameWidthVariableHover/$FrameHeightVariableHover: Hover variables
  • $HoverKeepExpanded: 1 to stay expanded
  • $GoBackToNonHoveredSizeAfter: Seconds to collapse
  • $HoverExpansionDirection: 0=rightUp, 1=leftUp, 2=rightDown, 3=leftDown, 4=leftRightDown, 5=leftRightUp, 6=upDownLeft, 7=upDownRight
  • $HoverStartAnimationDuration/$HoverEndAnimationDuration: Animation durations
  • $HoverDelay: Hover activation delay
  • $HoverWhileMousePressed: 1 to hover while dragging
  • §AnimateHover: 1 to animate hover

Window Properties​

  • $WindowLevel: 3=floating, 0=normal, 20=dock, 24=mainMenu, -1=custom
  • $WindowLevelManual: Custom level when $WindowLevel=-1
  • $WindowResizable: 1 to allow resizing
  • $TitleBarStyle: 0=noTitleBar, 1=standard, 2=overlayContent, 3=transparent
  • $ClickThroughEmptyParts: 1 to click through empty areas
  • $ClickThroughEverywhere: 1 to click through everywhere
  • $ShowDockIconWhileVisible: 1 to show dock icon
  • $ShowOnLockScreen: 1 to show on lock screen
  • $StealKeyboardFocusOnShow: 1 to steal focus

Visibility​

  • $Visibility: 0=onLaunch, 1=viaAction
  • $OpacityActive/$OpacityInactive: Opacity 0-1
  • $AlwaysUseLightMode: 1 to force light mode
  • $KeepCached: 1 to keep cached when hidden
  • $AnimateShow: 1 to animate appearance
  • $AnimateShowDuration: Animation duration
  • $AnimateChanges: 1 to animate property changes

Visibility Conditions​

  • $ShowIfWindowTitleIsNotEmpty: 1 to check
  • $ShowIfWindowTitleContains: String to match
  • $ShowIfAppNameContains: String to match
  • $ShowIfWindowTitleContainsNot: String to exclude
  • $ShowIfAppNameContainsNot: String to exclude
  • $ShowIfWindowLevelEqualsEnabled: 1 to enable check
  • $ShowIfWindowLevelEquals: Window level value
  • $ShowForWindowWithID: Only show for specific window ID
  • $DoNotShowInFullscreen: 1 to hide in fullscreen
  • $OnlyShowOnSpaces: Comma-separated space numbers

Interaction​

  • $CloseOnOutsideClick: 1 to close on outside click
  • $CloseOnMoveMouseAway: 1 to close when mouse leaves
  • $CloseOnKeyboardInput: 1 to close on keyboard
  • $CloseAfterAction: 1 to close after action
  • $DisableDrag: 1 to disable dragging
  • $ContinuouslyFollowMouse: 1 to make menu follow the mouse continuously
  • $KeepLastHoveredItemSelectedOnMouseOut: 1 to keep last hovered item selected when mouse leaves
  • $AllowScrolling: 1 to allow scrolling (default 1)
  • §CloseOnClick: 1 to close menu on item click (default 1)
  • §ShowHoverEffect: 1 to show hover effect (default 1)
  • §ShowIcon: 1 to show the item icon (default 1)

Alternate Mode​

  • $AlternateModeActive: 1 to activate alternate mode
  • $AlternateModeActiveVariable: BTT variable name that controls alternate mode

Merging​

  • $MergeGlobalMenuItems: 1 to merge items from global menu with same name

Modifiers​

  • §sUseModifierModes: true if items use modifiers
  • $ModifierMode: -1=none, 0=showIfPressed, 1=showIfOthersPressed, 2=showIfNonePressed, 3=showAlways, 4=showIfPressedShowNonModified, 5=showIfAtLeast, 6=dontShowIfPressed
  • $ModifierKeys: Bitmask of modifier keys

Scripting​

  • §ScriptActive: 1 to enable script
  • $ScriptSettings: Script configuration object
  • $ValueChangedScriptSettings: Script for value changes
  • $ScriptRunOnMenuHover: 1 to run on menu hover
  • $ScriptRunOnItemHover: 1 to run on item hover
  • $ScriptAlwaysRunOnFirstLoad: 1 to run on load
  • $ScriptUpdateInterval: Update interval in seconds
  • $ScriptAlwaysRunOnAppear: 1 to run on appear

Script Configuration ($ScriptSettings)​

  • ©ScriptType: 0=appleScript, 1=jax, 2=scpt, 3=realJavaScript, 4=shortcut
  • ©AppleScriptString: Script content
  • ©ScriptFunctionToCall: Function name
  • ©ScriptShortcutName: Shortcut name
  • ©ScriptLocation: 0=inline, 1=preset, 2/3=external
  • ©ScriptExternalPath: External script path
  • ©JavaScriptUseIsolatedContext: true for isolated JS

Item Properties​

Visibility​

  • §Disabled: 1 to disable
  • §VisibleWhileActive: 1 when menu hovered
  • §VisibleWhileInactive: 1 when not hovered
  • §VisibleIfVariableIsTrue: Variable name
  • §VisibleIfVariableIsFalse: Variable name
  • §DisplayOrder: Custom order value

Size & Position​

  • §MinWidth/§MaxWidth: Width constraints
  • §MinHeight/§MaxHeight: Height constraints
  • §PaddingLeft/Right/Top/Bottom: Internal padding
  • §MarginLeft/Right/Top/Bottom: External margin
  • §PositioningMode: 1 for manual positioning
  • §X/§Y: Manual position
  • §OffsetX/§OffsetY: Position offset

Text​

  • $AttributedText: RTF-encoded text
  • $AttributedTextDark: Dark mode RTF text
  • §Text: Plain text/HTML (for webviews)
  • $ElementIdentifier: Scripting identifier
  • $ElementTooltip: Tooltip text
  • §ShowIdentifierAsTooltip: 1=identifier, 2=tooltip
  • $TextMinimumScaleFactor: Min scale 0-1
  • $TextOffsetX/$TextOffsetY: Text offset
  • §FontColor/§FontColorHover: Font colors
  • §FontColorDark/§FontColorHoverDark: Dark mode font colors

Background​

  • §BackgroundType: 0=none, 1=data, 2=sfsymbol, 3=file, 4=color, 5=linearGradient, 6=radialGradient, 7=presetFile, 8=internal
  • §BackgroundColor/§BackgroundColor2/§BackgroundColor3/§BackgroundColor4: Gradient colors "R,G,B,A"
  • §BackgroundColorHover: Hover background
  • §BackgroundImageData: Base64 image data
  • §BackgroundImagePresetPath: Preset path
  • §BlurredBackground: 1 for blur effect
  • §GlassEffect: 1 for macOS Tahoe glass effect
  • Dark mode variants with Dark suffix (§BackgroundTypeDark, §BackgroundColorDark/§BackgroundColor2Dark/§BackgroundColor3Dark/§BackgroundColor4Dark, §BackgroundColorHoverDark, §BackgroundImageDataDark, §BackgroundImagePresetPathDark, §BlurredBackgroundDark, §GlassEffectDark)

Borders​

  • §BorderWidth: Border width
  • §BorderColor: Border color "R,G,B,A"
  • §BorderColorHover: Hover border color
  • §BorderDashed: 1 for dashed
  • §CornerRadius: Corner radius
  • §CornerRadiusCorners: 0=all, 1=left, 2=right, 3=top, 4=bottom, 5=topLeft, 6=topRight, 7=bottomRight, 8=bottomLeft
  • Dark mode variants with Dark suffix (§BorderWidthDark, §BorderColorDark, §BorderColorHoverDark, §BorderDashedDark, §CornerRadiusDark, §CornerRadiusCornersDark)

Shadow​

  • §ShadowEnabled: 1 to enable
  • §ShadowColor: Shadow color
  • §ShadowColorHover: Shadow color on hover
  • §ShadowRadius: Shadow radius
  • Dark mode variants with Dark suffix (§ShadowEnabledDark, §ShadowColorDark, §ShadowColorHoverDark, §ShadowRadiusDark)

Icons/Images​

  • §IconType: Same as §BackgroundType
  • §IconPosition: 0=left, 1=top, 2=right, 3=bottom, 4=center, 5=none
  • §Image: Base64 image data
  • §IconPresetPath: Preset icon path
  • §ResizeImage: 0=fit, 1=none, 2=fixed, 3=fitNew
  • §ImageChangeColor: 1 to tint with icon color
  • §ImageWidth: Image width
  • §ImageHeight: Image height
  • §ImageOffsetX/Y: Image offset
  • §ImagePadding: Image padding
  • Dark mode variants with Dark suffix (§IconTypeDark, §IconPositionDark, §ImageDark, §IconPresetPathDark, §ResizeImageDark, §ImageChangeColorDark, §ImageWidthDark, §ImageHeightDark, §ImageOffsetXDark/YDark, §ImagePaddingDark)

SF Symbols​

  • §SFSymbolName: Symbol name
  • §SFSymbolWeight: Symbol weight
  • §SFSymbolStyle: 0=monochrome, 1=hierarchical, 2=palette, 3=multiColor
  • §IconColor1/§IconColor2/§IconColor3: Symbol colors (palette uses 2-3 colors, hierarchical uses 1)
  • §IconColor1Hover/§IconColor2Hover/§IconColor3Hover: Hover colors
  • Dark mode variants with Dark suffix (§SFSymbolNameDark, §SFSymbolWeightDark, §SFSymbolStyleDark, §IconColor1Dark/§IconColor2Dark/§IconColor3Dark, §IconColor1HoverDark/§IconColor2HoverDark/§IconColor3HoverDark)

WebView Properties​

  • §WebViewPlain: 1 for plain HTML
  • §UserAgent: Custom user agent
  • §UserScript: Script on load
  • §UserScriptOnvisible: Script on visible
  • §WebViewFocusTextField: 1 to auto-focus
  • §WebViewFocusTextFieldWithID: Field ID
  • §KeepActiveInBackground: 1 to keep active
  • §SystemBrowserPrefix: External URL prefixes
  • §SystemBrowserPrefixOverrides: Override prefixes
  • §SystemBrowserClosesMenu: 1 to close on external

Circular Layout​

  • $HoverOnWholePizzaSlice: 1 for whole wedge hover
  • $HighlightPizzaSlice: 1 to highlight wedge
  • $PlaceFirstItemAtCenter: 1 to center first item
  • §PizzaSliceBackgroundColor: Wedge background
  • §PizzaSliceBorderColor: Wedge border
  • §PizzaSliceBorderWidth: Border width
  • Dark mode variants with Dark suffix (§PizzaSliceBackgroundColorDark, §PizzaSliceBorderColorDark, §PizzaSliceBorderWidthDark)

Interaction​

  • §Focused: 1 for initial focus
  • §ScrollEnabled: 1 to enable scroll
  • §ScrollDelta: Touch scroll delta
  • §ScrollDeltaNormalMouse: Mouse scroll delta

Folder Widget Properties​

  • §Path: Folder path to display (e.g. "/Applications/BetterTouchTool.app")

Widget Properties (General)​

  • $WidgetStringStringDictionary: String dictionary
  • $WidgetStringIntDictionary: Integer dictionary
  • $WidgetCustomPluginID: Plugin bundle identifier for custom widgets

Now Playing Widget​

  • $WidgetNowPlayingPauseBehavior: 0=icon, 1=albumcover
  • $WidgetNowPlayingHideCover: 0=album cover, 1=app icon, 2=hidden
  • $WidgetNowPlayingShowAlbum: 0=hide, 1=show
  • $WidgetNowPlayingHideWhenPaused: 0=show, 1=show paused, 2=hide
  • $WidgetNowPlayingHideWhenNoPlayer: 0=show, 1=hide
  • $WidgetNowPlayingLayout: 0=horizontal, 1=vertical
  • $WidgetNowPlayingShowProgress: 0=hidden, 1=show progress bar
  • $WidgetNowPlayingAllowedApps: Comma-separated bundle IDs (empty=all)

Weather Widget​

  • $WidgetWeatherUnit: 0=Celsius, 1=Fahrenheit, 2=System
  • $WidgetWeatherAutoLocation: 0=manual, 1=auto (default)
  • $WidgetWeatherLatLon: "lat,lon" for manual location
  • $WidgetWeatherLayout: 0=variables mode, 1=rich SwiftUI
  • $WidgetWeatherForecastDay: -1=current, 0-7=forecast day
  • $WidgetWeatherHideWhenNoData: 0=show, 1=hide

Trackpad Widget​

  • $WidgetTrackpadFingerMoveColor: Finger move color
  • $WidgetTrackpadFingerDragColor: Finger drag color
  • $WidgetTrackpadFingerScrollColor: Finger scroll color
  • $WidgetTrackpadEdgeScroll: 1 to enable edge scroll
  • $WidgetTrackpadEdgeRightClick: 1 to enable edge right-click
  • $WidgetTrackpadTwoFingerScroll: 1 to enable two-finger scroll
  • $WidgetTrackpadTwoFingerRightClick: 1 to enable two-finger right-click
  • $WidgetTrackpadThreeFingerMiddleClick: 1 to enable three-finger middle-click
  • $WidgetTrackpadInertialCursor: 1 to enable inertial cursor
  • $WidgetTrackpadBigCursor: 1 to enable big cursor

Miscellaneous​

  • $UseStyleForSubmenu: 1 to inherit parent style
  • $OverrideGlobalMenuSetttings: 1 to override globals
  • $CreatedViaScript: 1 if script-created
  • $OnlyCopyOpenCategories: 1 for categories
  • §Extras: Extra data (future use)
  • ©AnimateUUID: Animation trigger UUID
  • ©LastChangeUUID: Last change UUID

Actions (§Actions)​

"§Actions": [{
  "©PredefinedActionType": 5,
  "©PredefinedActionName": "Mission Control",
  "©Enabled": 1,
  "©Order": 0
}]

Default Values​

Properties listed below can be omitted from $Config when their value matches the default — the runtime will behave identically whether the key is present-with-default or absent. This keeps exported JSON minimal.

Defaults = 0​

§MarginLeft, §MarginRight, §MarginTop, §MarginBottom, §MinWidth, §MinHeight, §ShadowEnabled, §ShadowEnabledDark, §ShadowEnabledAlt, §BorderWidth, §BorderWidthDark, §BorderWidthAlt, §PositioningMode, §X, §Y, §OffsetX, §OffsetY, §ImageOffsetX, §ImageOffsetY, §ImageOffsetXDark, §ImageOffsetXAlt, §ImageOffsetYDark, §ImageOffsetYAlt, §ImagePadding, §ImagePaddingDark, §ImagePaddingAlt, $TextOffsetX, $TextOffsetY, §BlurredBackground, §GlassEffect, §GlassEffectDark, §DisplayOrder, §ScrollDelta, §InternalProperty2, $DisableDrag, $CloseAfterAction, $CloseOnMoveMouseAway, $CloseOnKeyboardInput, $OffsetX, $OffsetY, $ResizeOnHover, $HighlightPizzaSlice, $HoverOnWholePizzaSlice, $PlaceFirstItemAtCenter, $WindowResizable, $HorizontalAlignment, $VerticalAlignment, $ShowIfWindowLevelEqualsEnabled, $AnimateShow, $AnimateShowDuration, $FrameWidthHovered, $FrameHeightHovered, $ScriptAlwaysRunOnFirstLoad, $ScriptAlwaysRunOnAppear, $ModifierKeys, $WidgetNowPlayingHideCover, $WidgetNowPlayingHideWhenNoPlayer, $WidgetNowPlayingHideWhenPaused, $WidgetWeatherLayout, $WidgetWeatherUnit, $WidgetWeatherHideWhenNoData

Defaults = 1​

$TextMinimumScaleFactor, $OpacityActive, $OpacityInactive, §VisibleWhileActive, §VisibleWhileInactive, §ShowHoverEffect, §ShowIcon, §CloseOnClick, $AllowScrolling, $CloseOnOutsideClick, $WidgetWeatherAutoLocation

Defaults = 2​

§ScrollDeltaNormalMouse

Defaults = 5​

§PaddingLeft, §PaddingRight, §PaddingTop, §PaddingBottom

Defaults = 10000​

§MaxWidth, §MaxHeight

Defaults = -1​

$WidgetWeatherForecastDay

Always excluded from export​

$AppearanceStyle, ©LastChangeUUID, §IsVisible (internal only)

Example: Complete Menu​

[{
  "©TriggerType": 767,
  "©UUID": "menu-uuid",
  "©Enabled": 1,
  "$Name": "Example Menu",
  "$Config": {
    "$PositioningType": 1,
    "$PositionRelativeTo": 3,
    "$AnchorMenu": 1,
    "$AnchorRelation": 1,
    "$FrameWidth": 220,
    "$FrameHeight": 300,
    "$OpacityActive": 1,
    "$OpacityInactive": 0.8,
    "$LayoutDirection": 0,
    "$VerticalSpacing": 5,
    "$HorizontalSpacing": 5,
    "$WindowLevel": 3,
    "$CloseAfterAction": 1
  },
  "§s": [{
    "©TriggerType": 773,
    "©TriggerParentUUID": "menu-uuid",
    "©UUID": "item-uuid",
    "©Enabled": 1,
    "$Name": "Click Me",
    "$Config": {
      "§VisibleWhileActive": 1,
      "§VisibleWhileInactive": 1,
      "§MinWidth": 100,
      "§MinHeight": 50,
      "§BackgroundType": 4,
      "§BackgroundColor": "90, 180, 240, 255",
      "§BackgroundColorHover": "120, 200, 255, 255",
      "§CornerRadius": 10,
      "§BorderWidth": 2,
      "§BorderColor": "255, 255, 255, 128",
      "$AttributedText": "{\\rtf1 Click Me}",
      "§IconType": 2,
      "§SFSymbolName": "hand.tap",
      "§IconColor1": "255, 255, 255, 255"
    },
    "§Actions": [{
      "©PredefinedActionType": 5,
      "©PredefinedActionName": "Mission Control"
    }]
  }]
}]

Color Format​

Colors use "R, G, B, A" format (0-255): "255, 0, 0, 255" = opaque red

Import Method​

ai.create_bettertouchtool_trigger(json: theJSONAsString)