Floating Menu Items
A floating menu can contain several types of items. It can also load external Swift / SwiftUI plugin items; see Custom Swift Plugin Widgets. Every item has a unique identifier (UUID) by default. You can get it by right-clicking the item. Some item-related actions need this identifier. You can also enter a custom identifier/name in the Item Name / Identifier field:
Standard Item
Standard items show text and icons / images. They're scriptable and probably the most useful kind of menu item. You can drop files onto a standard item. To access the dropped files, read the item's value (see Get dropped item values).
Web View Items
Web View items can load any HTML content, either from a URL or from HTML you provide directly. They're based on BTT's Floating Webview, which makes them quite powerful. They can run AppleScript, shell scripts, Shortcuts and more.
For details, see Floating HTML / Web Views.
You can change the content of a web view item by loading a new URL and/or running JavaScript inside the web view:
Loading Content Into A Web View Item or Executing JavaScript
JavaScript Example: Load https://apple.com:
(async ()=> {
await webview_menu_item_load_html_url_js(
{
"item_uuid": "4FAAE4F8-5858-4444-A0E4-3498B7534CF2",
"html_or_url": "https://apple.com"
}
)
returnToBTT('done');
})()
AppleScript Example: Load https://apple.com
tell application "BetterTouchTool"
# instead of the uuid you can also use the item_name and menu_name parameters.
webview_menu_item_load_html_url_js "9E2989CF-77C7-4F14-A646-49342D2F8331" html_or_url "https://apple.com"
end tell
JavaScript Example: Show Alert:
(async ()=> {
await webview_menu_item_load_html_url_js(
{
"menu_name": "TheMenuName",
"item_name": "TheItem",
"javascript_to_execute": "alert('hello world');"
}
)
returnToBTT('done');
})()
AppleScript Example: Show Alert
tell application "BetterTouchTool"
# instead of the uuid you can also use the item_name and menu_name parameters.
webview_menu_item_load_html_url_js "9E2989CF-77C7-4F14-A646-49342D2F8331" javascript_to_execute "alert('hello world')"
end tell
Slider Items
Slider items show a scriptable slider. Each one has two scripts: one that retrieves the current/initial value (set up in the item's Content Script section) and one that runs when you drag the slider (set up in the Value Change Script tab).
Here's an example preset with such a slider: https://share.folivora.ai/sP/80d02742-50ec-45a3-833f-5b9ee8144e72
The initialization script should return a value between 0 and 1, plus the label to show to the right of the slider. Return both as JSON/JSON5, like in this example:
return "{BTTMenuItemText: '50%', BTTMenuItemValue: 0.5}"
The change script needs to look like this. It should return the formatted label (if any):
on sliderChanged(uuid, value)
set volume output volume value * 100
set roundedValue to round value * 100
set formattedValue to roundedValue & "%"
return "{BTTMenuItemText: '" & formattedValue & "' }"
end sliderChanged
Textfield Items
Text field items let you enter text. You can read that text through the floating menu scripting interfaces. See Scripting Floating Menus.
Widgets
BetterTouchTool includes several built-in widget items: Now Playing Widget, Weather Widget, Drawer Widget, Launchpad Widget, Folder View Widget/Item and App Widget/Item. Each one has its own configuration tab next to the general item configuration. You can also use Custom Widget Plugin items; see Custom Swift Plugin Widgets.
Window Stream
A Window Stream item shows a live window of your Mac inside a floating menu, and you can use it right there. It works in menus on the Mac and on BTT Mobile, where it works like BTT Mobile's window viewer and can also show a whole screen (see Mac Windows on Your iPad or iPhone).
- Which window: set App (name or bundle identifier) and/or Window Title Contains in the item's Window Stream Config tab, and the item shows the first matching window whenever the menu appears. Leave both empty to pick the window in the menu itself (Choose Window…; on BTT Mobile a screen works too). The choice is remembered, separately on the Mac and on each device, and the small button in the item's corner picks another one.
- On the Mac: click, scroll and drag in the item as in the window itself. A click also gives the item the keyboard (a thin ring shows it): what you type goes to the window, while its app stays in the background and the window stays where it is. Drag files or text out of the window to anywhere, or drag something onto the item: after a moment the real window comes over the item to take the drop, and goes back afterwards. BetterTouchTool needs the Screen Recording and Accessibility permissions.
- Touch Input (BTT Mobile): Trackpad (default) moves a pointer with your finger, Direct Touch clicks where you tap. Like the trackpad item, trackpad mode can scroll with one finger along the right or bottom edge and right-click with a tap at the right edge (two checkboxes, off by default). Pinch zooms the picture, and the keyboard button in the corner brings up the keyboard, with the same key strip on top of it as in the full-screen viewer (Esc, Tab, ⌃ ⌥ ⇧ ⌘, the arrow keys and F1–F12) and a button at its end that hides the keyboard again. If the keys don't all fit, swipe the strip sideways.
- Window Size: keep the Mac window's size, or give it the item's shape: at the item's size (100 %), or two or three times as large (50 % / 33 %), which most windows need to be usable.
- Window Placement: follow the window streaming setting, keep the window where it is (a mirror you can keep using there; macOS only updates it while it isn't covered), or move it to the invisible display (always live; in Mac menus the window comes back about 10 seconds after the menu hides).
Each item has its own stream, so it doesn't interrupt the full-screen viewer or other items. For BTT Mobile, window streaming has to be allowed in Settings › BTT Mobile › Window Streaming on the Mac.
Launchpad Widget
The Launchpad widget shows all installed apps in pages, like the classic macOS Launchpad that was removed in macOS 26:
- Type to search (enable Steal Keyboard Focus On Show on the menu), use the arrow keys and Return to launch. Escape closes an open folder, leaves edit mode, clears the search and finally hides the menu.
- Swipe with two fingers, scroll or click the page dots to change pages.
- Drag an app to rearrange it (a long press also enters the "jiggle" edit mode). Rest it on another app to create a folder, drag it out of an open folder to remove it. In edit mode the badge hides an app.
- Right-click for Hidden Apps (show them again), Import macOS Launchpad Layout (reads the layout of the old Launchpad if your Mac still has it), Reset Layout and Refresh App List.
- The widget configuration tab sets columns, rows, icon size, label size, alphabetical or custom order and whether the menu stays open after launching an app. Set the label color under App Label Colors in the item's appearance settings (with a separate color for dark mode). Hovering an icon highlights it with the item's hover background color, and the whole highlighted area opens the app. The widget always fills its menu; the item's max width / height only limit the centered app grid, which also stays below the notch / menu bar.
The layout (order, folders, hidden apps) is stored per widget in ~/Library/Application Support/BetterTouchTool/LaunchpadWidgets/.
To get a fullscreen Launchpad that toggles with the classic "pinch with thumb and three fingers" gesture, import this preset (and turn off the macOS gesture for Launchpad/Apps in System Settings > Trackpad > More Gestures):
[
{
"BTTTriggerType": 767,
"BTTTriggerClass": "BTTTriggerTypeFloatingMenu",
"BTTEnabled": 1,
"BTTMenuName": "Launchpad",
"BTTMenuConfig": {
"BTTMenuElementIdentifier": "Launchpad",
"BTTMenuVisibility": 1,
"BTTMenuPositioningType": 1,
"BTTMenuPositionRelativeTo": 1,
"BTTMenuAnchorMenu": 0,
"BTTMenuAnchorRelation": 0,
"BTTMenuSizingBehavior": 2,
"BTTMenuFrameWidth": 1200,
"BTTMenuFrameHeight": 800,
"BTTMenuFrameWidthVariable": "mouse_screen_width",
"BTTMenuFrameHeightVariable": "mouse_screen_height",
"BTTMenuStealKeyboardFocusOnShow": 1,
"BTTMenuWindowLevel": -1,
"BTTMenuWindowLevelManual": 25,
"BTTMenuLayoutDirection": 6,
"BTTMenuDisableDrag": 1,
"BTTMenuItemBackgroundType": 4,
"BTTMenuItemBackgroundTypeDark": 4,
"BTTMenuItemBackgroundColor": "30, 30, 40, 120",
"BTTMenuItemBackgroundColorDark": "20, 20, 28, 140",
"BTTMenuItemBlurredBackground": 1,
"BTTMenuItemBlurredBackgroundDark": 1,
"BTTMenuItemCornerRadius": 0,
"BTTMenuItemPaddingTop": 0,
"BTTMenuItemPaddingBottom": 0,
"BTTMenuItemPaddingLeft": 0,
"BTTMenuItemPaddingRight": 0,
"BTTMenuAnimateShow": 1,
"BTTMenuAnimateShowDuration": 0.15
},
"BTTMenuItems": [
{
"BTTTriggerType": 941,
"BTTTriggerClass": "BTTTriggerTypeFloatingMenu",
"BTTEnabled": 1,
"BTTMenuConfig": {
"BTTMenuItemVisibleWhileActive": 1,
"BTTMenuItemVisibleWhileInactive": 1,
"BTTMenuItemMinWidth": 720,
"BTTMenuItemMaxWidth": 10000,
"BTTMenuItemMinHeight": 460,
"BTTMenuItemMaxHeight": 10000,
"BTTMenuItemBackgroundType": 0,
"BTTMenuItemBackgroundTypeDark": 0,
"BTTMenuItemFontColor": "255, 255, 255, 255",
"BTTMenuItemFontColorDark": "255, 255, 255, 255",
"BTTMenuItemBackgroundColorHover": "255, 255, 255, 46",
"BTTMenuItemBackgroundColorHoverDark": "255, 255, 255, 46"
}
}
]
},
{
"BTTTriggerType": 194,
"BTTTriggerClass": "BTTTriggerTypeTouchpadAll",
"BTTEnabled": 1,
"BTTActionsToExecute": [
{
"BTTPredefinedActionType": 388,
"BTTAdditionalActionData": {
"BTTMenuActionMenuID": "Launchpad",
"BTTMenuActionActivateKeyboardFocus": 1
}
}
]
}
]