Popups

Popups are menus or windows that can be attached to any bar item. They appear when an item is clicked and can contain their own set of SketchyBar items. This is an excellent way to display more detailed information or provide interactive controls without cluttering the main bar.

Creating a Popup Item

Creating an item that belongs to a popup is done by setting its position property to popup.<parent_name>.

# 1. First, create the parent item that will trigger the popup
sketchybar --add item sys_info right \
           --set sys_info icon=⚙️ \
           --subscribe sys_info mouse.clicked

# 2. Now, add an item that will appear inside the popup
sketchybar --add item cpu_details popup.sys_info \
           --set cpu_details label="CPU: ..."

• popup.sys_info: This tells SketchyBar that cpu_details is an item belonging to the popup of sys_info.

Controlling Popup Visibility

Popups are toggled using the popup.drawing property of the parent item.

# To show the popup
sketchybar --set sys_info popup.drawing=on

# To hide the popup
sketchybar --set sys_info popup.drawing=off

A common pattern is to use a click_script on the parent item to toggle its own popup.

# A simple toggle script for the 'sys_info' item
IS_VISIBLE=$(sketchybar --query sys_info | jq -r '.popup.drawing')

if [ "$IS_VISIBLE" = "off" ]; then
  sketchybar --set sys_info popup.drawing=on
else
  sketchybar --set sys_info popup.drawing=off
fi

Popup Properties

You can style the popup window itself by setting properties prefixed with popup. on the parent item.

• popup.background.color=<HEX_COLOR>: Sets the background color of the popup window.
• popup.background.corner_radius=<INT>: Sets the corner radius of the popup window.
• popup.background.border_width=<INT>
• popup.background.border_color=<HEX_COLOR>
• popup.blur_radius=<INT>: Sets the background blur for the popup.
• popup.y_offset=<INT>: Vertically offsets the popup relative to the parent item.
• popup.horizontal=<on|off>: If on, items inside the popup are arranged horizontally instead of vertically.
• popup.height=<INT>: Sets the height of each cell/row in a vertical popup.
• popup.align=<left|center|right>: Aligns the popup window relative to the parent item.

Example: Styling a Popup

sketchybar --set sys_info \
           popup.horizontal=on \
           popup.background.corner_radius=8 \
           popup.background.color=0x90282738 \
           popup.background.border_color=0xffcba6f7 \
           popup.background.border_width=2 \
           popup.blur_radius=20

This would create a horizontal popup for the sys_info item with a styled, blurred background.