Events and Scripting

The event system is a cornerstone of SketchyBar's efficiency and power. Instead of constantly polling for changes, items can subscribe to events and run their scripts only when a relevant change occurs.

Subscribing to Events

You subscribe an item to one or more events using the --subscribe command.

# Syntax: sketchybar --subscribe <item_name> <event_1> <event_2> ...

sketchybar --subscribe volume_icon volume_change \
           --subscribe music_info media_change

When the specified event is triggered, the script associated with the subscribed item is executed.

Environment Variables

When an event triggers a script, it provides context through environment variables:

$NAME: The name of the item whose script is being run.
$SENDER: The name of the event that triggered the script.
$INFO: A string containing data specific to the event (e.g., the new volume level, the name of the new application).

Built-in Events

SketchyBar provides a rich set of built-in events you can subscribe to.

Event Name	`$INFO` Payload	Description
`front_app_switched`	The name of the new frontmost application.	Triggered when the active application changes.
`space_change`	A JSON object with display IDs and their active space IDs.	Triggered when the active Mission Control space changes on any display.
`display_change`	The arrangement ID of the new active display.	Triggered when the active display changes (the one with the focused window).
`system_woke`	-	Triggered when the system wakes from sleep.
`system_will_sleep`	-	Triggered just before the system goes to sleep.
`volume_change`	The new volume level as a percentage (0-100).	Triggered when the system audio volume changes.
`wifi_change`	The current Wi-Fi network SSID.	Triggered when the Wi-Fi network changes.
`brightness_change`	The new brightness level as a percentage (0-100).	Triggered when the screen brightness changes.
`power_source_change`	"AC" or "BATTERY".	Triggered when the power source (adapter or battery) changes.
`media_change`	A JSON object with media player state and track info.	Triggered when the playing track, artist, or player state changes.
`space_windows_change`	A JSON object detailing apps and window counts per space.	Triggered when a window is opened, closed, or moved between spaces.
`mouse.clicked`	A JSON object with mouse button and modifier key info.	Triggered on a mouse click on the item.
`mouse.entered`	-	Triggered when the mouse cursor enters the item's area.
`mouse.exited`	-	Triggered when the mouse cursor leaves the item's area.
`mouse.scrolled`	A JSON object with scroll delta and modifier key info.	Triggered when the mouse is scrolled over the item.
`mouse.entered.global`	-	Triggered when the mouse enters any SketchyBar area (bar or popups).
`mouse.exited.global`	-	Triggered when the mouse leaves all SketchyBar areas.
`mouse.scrolled.global`	A JSON object with scroll delta, display ID, and modifiers.	Triggered when scrolling over the main bar.

Custom Events

You can define your own custom events, which is useful for creating complex interactions between different items or for receiving notifications from external scripts.

1. Adding a Custom Event

First, you must register the event name with SketchyBar.

# Syntax: sketchybar --add event <event_name>

sketchybar --add event my_custom_event

2. Subscribing to the Custom Event

Once added, you can subscribe items to it just like a built-in event.

sketchybar --subscribe my_item my_custom_event

3. Triggering the Custom Event

Finally, you can trigger the event from anywhere using the --trigger command. You can also pass custom key-value pairs that will be available in the subscribing script's environment.

# Syntax: sketchybar --trigger <event_name> [optional: <key>=<value> ...]

sketchybar --trigger my_custom_event INFO="Hello World" CUSTOM_VAR="123"

The script for my_item would then execute with $SENDER set to my_custom_event, $INFO set to Hello World, and $CUSTOM_VAR set to 123.