<titledata-rh="true">Events & Scripting | SketchyBar</title><metadata-rh="true"name="viewport"content="width=device-width,initial-scale=1"><metadata-rh="true"name="twitter:card"content="summary_large_image"><metadata-rh="true"property="og:url"content="https://felixkratz.github.io/SketchyBar/config/events"><metadata-rh="true"name="docusaurus_locale"content="en"><metadata-rh="true"name="docsearch:language"content="en"><metadata-rh="true"name="docusaurus_version"content="current"><metadata-rh="true"name="docusaurus_tag"content="docs-default-current"><metadata-rh="true"name="docsearch:version"content="current"><metadata-rh="true"name="docsearch:docusaurus_tag"content="docs-default-current"><metadata-rh="true"property="og:title"content="Events & Scripting | SketchyBar"><metadata-rh="true"name="description"content="Events and Scripting"><metadata-rh="true"property="og:description"content="Events and Scripting"><linkdata-rh="true"rel="icon"href="/SketchyBar/img/favicon.ico"><linkdata-rh="true"rel="canonical"href="https://felixkratz.github.io/SketchyBar/config/events"><linkdata-rh="true"rel="alternate"href="https://felixkratz.github.io/SketchyBar/config/events"hreflang="en"><linkdata-rh="true"rel="alternate"href="https://felixkratz.github.io/SketchyBar/config/events"hreflang="x-default"><linkrel="stylesheet"href="/SketchyBar/assets/css/styles.21661fb5.css">
events rather than polling for a change.</p><divclass="language-bash codeBlockContainer_Ckt0 theme-code-block"style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><divclass="codeBlockContent_biex"><pretabindex="0"class="prism-code language-bash codeBlock_bY9V thin-scrollbar"><codeclass="codeBlockLines_e6Vv"><spanclass="token-line"style="color:#bfc7d5"><spanclass="token plain">sketchybar --subscribe </span><spanclass="token operator"style="color:rgb(137, 221, 255)"><</span><spanclass="token plain">name</span><spanclass="token operator"style="color:rgb(137, 221, 255)">></span><spanclass="token plain"></span><spanclass="token operator"style="color:rgb(137, 221, 255)"><</span><spanclass="token plain">event</span><spanclass="token operator"style="color:rgb(137, 221, 255)">></span><spanclass="token plain"></span><spanclass="token punctuation"style="color:rgb(199, 146, 234)">..</span><spanclass="token plain">. </span><spanclass="token operator"style="color:rgb(137, 221, 255)"><</span><spanclass="token plain">event</span><spanclass="token operator"style="color:rgb(137, 221, 255)">></span><br></span></code></pre><divclass="buttonGroup__atx"><buttontype="button"aria-label="Copy code to clipboard"title="Copy"class="clean-btn"><spanclass="copyButtonIcons_eSgA"aria-hidden="true"><svgclass="copyButtonIcon_y97N"viewBox="0 0 24 24"><pathd="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svgclass="copyButtonSuccessIcon_LjdS"viewBox="0 0 24 24"><pathd="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><p>where the events are:</p><table><thead><tr><thalign="center"><event<!---->></th><thalign="center">description</th><thalign="center"><code>$INFO</code></th></tr></thead><tbody><tr><tdalign="center"><code>front_app_switched</code></td><tdalign="center">When the front application changes (not triggered if a different window of the same app is focused)</td><tdalign="center">front application name</td></tr><tr><tdalign="center"><code>space_change</code></td><tdalign="center">When the active mission control space changes</td><tdalign="center">JSON for active spaces on all displays</td></tr><tr><tdalign="center"><code>display_change</code></td><tdalign="center">When the active display is changed</td><tdalign="center">new active display id</td></tr><tr><tdalign="center"><code>volume_change</code></td><tdalign="center">When the system audio volume is changed</td><tdalign="center">new volume in percent</td></tr><tr><tdalign="center"><code>brightness_change</code></td><tdalign="center">When a displays brightness is changed</td><tdalign="center">new brightness in percent</td></tr><tr><tdalign="center"><code>power_source_change</code></td><tdalign="center">When the devices power source is changed</td><tdalign="center">new power source (<code>AC</code> or <code>BATTERY</code>)</td></tr><tr><tdalign="center"><code>wifi_change</code></td><tdalign="center">When the device connects of disconnects from wifi</td><tdalign="center">new WiFi SSID or empty on disconnect</td></tr><tr><tdalign="center"><code>system_will_sleep</code></td><tdalign="center">When the system prepares to sleep</td><tdalign="center"></td></tr><tr><tdalign="center"><code>system_woke</code></td><tdalign="center">When the system has awaken from sleep</td><tdalign="center"></td></tr><tr><tdalign="center"><code>mouse.entered</code></td><tdalign="center">When the mouse enters over an item</td><tdalign="center"></td></tr><tr><tdalign="center"><code>mouse.exited</code></td><tdalign="center">When the mouse leaves an item</td><tdalign="center"></td></tr><tr><tdalign="center"><code>mouse.entered.global</code></td><tdalign="center">When the mouse enters over <em>any</em> part of the bar</td><tdalign="center"></td></tr><tr><tdalign="center"><code>mouse.exited.global</code></td><tdalign="center">When the mouse leaves <em>all</em> parts of th
When an item is subscribed to these events the <em>script</em> is run and it gets passed the <code>$SENDER</code> variable, which holds exactly the above names to distinguish between the different events.
It is thus possible to have a script that reacts to each event differently e.g. via a switch for the <code>$SENDER</code> variable in the <em>script</em>.</p><p>Alternatively a fixed <em>update_freq</em> can be <em>--set</em>, such that the event is routinely run to poll for change, the <code>$SENDER</code> variable will in this case hold the value <code>routine</code>.</p><p>When an item invokes a script, the script has access to some environment variables, such as:</p><divclass="language-bash codeBlockContainer_Ckt0 theme-code-block"style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><divclass="codeBlockContent_biex"><pretabindex="0"class="prism-code language-bash codeBlock_bY9V thin-scrollbar"><codeclass="codeBlockLines_e6Vv"><spanclass="token-line"style="color:#bfc7d5"><spanclass="token variable"style="color:rgb(191, 199, 213)">$NAME</span><spanclass="token plain"></span><br></span><spanclass="token-line"style="color:#bfc7d5"><spanclass="token plain"></span><spanclass="token variable"style="color:rgb(191, 199, 213)">$SENDER</span><br></span></code></pre><divclass="buttonGroup__atx"><buttontype="button"aria-label="Copy code to clipboard"title="Copy"class="clean-btn"><spanclass="copyButtonIcons_eSgA"aria-hidden="true"><svgclass="copyButtonIcon_y97N"viewBox="0 0 24 24"><pathd="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svgclass="copyButtonSuccessIcon_LjdS"viewBox="0 0 24 24"><pathd="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><p>Where <code>$NAME</code> is the name of the item that has invoked the script and <code>$SENDER</code> is the reason why the script is executed.</p><p>If an item is <em>clicked</em> the script has access to the additional variables:</p><divclass="language-bash codeBlockContainer_Ckt0 theme-code-block"style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><divclass="codeBlockContent_biex"><pretabindex="0"class="prism-code language-bash codeBlock_bY9V thin-scrollbar"><codeclass="codeBlockLines_e6Vv"><spanclass="token-line"style="color:#bfc7d5"><spanclass="token variable"style="color:rgb(191, 199, 213)">$BUTTON</span><spanclass="token plain"></span><br></span><spanclass="token-line"style="color:#bfc7d5"><spanclass="token plain"></span><spanclass="token variable"style="color:rgb(191, 199, 213)">$MODIFIER</span><br></span></code></pre><divclass="buttonGroup__atx"><buttontype="button"aria-label="Copy code to clipboard"title="Copy"class="clean-btn"><spanclass="copyButtonIcons_eSgA"aria-hidden="true"><svgclass="copyButtonIcon_y97N"viewBox="0 0 24 24"><pathd="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svgclass="copyButtonSuccessIcon_LjdS"viewBox="0 0 24 24"><pathd="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><p>where the <code>$BUTTON</code> can be <em>left</em>, <em>right</em> or <em>other</em> and specifies the mouse button that was used to click the item, while the <code>$MODIFIER</code> is either <em>shift</em>, <em>ctrl</em>, <em>alt</em> or <em>cmd</em> and
specifies the modifier key held down while clicking the item.</p><p>All scripts are forced to terminate after 60 seconds and do not run while the system is sleeping. </p><h3class="anchor anchorWithStickyNavbar_LWe7"id="creating-custom-events">Creating custom events<aclass="hash-link"href="#creating-custom-events"title="Direct link to heading"></a></h3><p>This allows to define events which are triggered by arbitrary applications or manually (see Trigger custom events).
Items can also subscribe to these events for their script execution.</p><divclass="language-bash codeBlockContainer_Ckt0 theme-code-block"style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><divclass="codeBlockContent_biex"><pretabindex="0"class="prism-code language-bash codeBlock_bY9V thin-scrollbar"><codeclass="codeBlockLines_e6Vv"><spanclass="token-line"style="color:#bfc7d5"><spanclass="token plain">sketchybar --add event </span><spanclass="token operator"style="color:rgb(137, 221, 255)"><</span><spanclass="token plain">name</span><spanclass="token operator"style="color:rgb(137, 221, 255)">></span><spanclass="token plain"></span><spanclass="token punctuation"style="color:rgb(199, 146, 234)">[</span><spanclass="token plain">optional: </span><spanclass="token operator"style="color:rgb(137, 221, 255)"><</span><spanclass="token plain">NSDistributedNotificationName</span><spanclass="token operator"style="color:rgb(137, 221, 255)">></span><spanclass="token punctuation"style="color:rgb(199, 146, 234)">]</span><br></span></code></pre><divclass="buttonGroup__atx"><buttontype="button"aria-label="Copy code to clipboard"title="Copy"class="clean-btn"><spanclass="copyButtonIcons_eSgA"aria-hidden="true"><svgclass="copyButtonIcon_y97N"viewBox="0 0 24 24"><pathd="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svgclass="copyButtonSuccessIcon_LjdS"viewBox="0 0 24 24"><pathd="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><p>Optional: You can subscribe to the notifications sent to the NSDistributedNotificationCenter e.g.
<code>com.spotify.client.PlaybackStateChanged</code> (<ahref="https://github.com/FelixKratz/SketchyBar/discussions/12#discussioncomment-1455842"target="_blank"rel="noopener noreferrer">example</a>), or the
notification sent by the system when the screen is unlocked:
