<titledata-rh="true">Events & Scripting | SketchyBar</title><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.d31a9c85.css">
This can be used to create more reactive and performant items which react to events rather than polling for a change.</p><divclass="codeBlockContainer_I0IT language-bash theme-code-block"><divclass="codeBlockContent_wNvx"style="color:#bfc7d5;background-color:#292d3e"><pretabindex="0"class="prism-code language-bash codeBlock_jd64 thin-scrollbar"><codeclass="codeBlockLines_mRuA"><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><buttontype="button"aria-label="Copy code to clipboard"title="Copy"class="copyButton_eDfN clean-btn"><spanclass="copyButtonIcons_W9eQ"aria-hidden="true"><svgclass="copyButtonIcon_XEyF"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_i9w9"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><p>where the events are:</p><table><thead><tr><thalign="center"><event<!---->></th><thalign="center">description</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></tr><tr><tdalign="center"><code>space_change</code></td><tdalign="center">When the active mission control space changes</td></tr><tr><tdalign="center"><code>display_change</code></td><tdalign="center">When the active display is changed</td></tr><tr><tdalign="center"><code>system_will_sleep</code></td><tdalign="center">When the system prepares to sleep</td></tr><tr><tdalign="center"><code>system_woke</code></td><tdalign="center">When the system has awaken from sleep</td></tr><tr><tdalign="center"><code>mouse.entered</code></td><tdalign="center">When the mouse enters over an item</td></tr><tr><tdalign="center"><code>mouse.exited</code></td><tdalign="center">When the mouse leaves an item</td></tr><tr><tdalign="center"><code>mouse.clicked</code></td><tdalign="center">When an item is clicked</td></tr></tbody></table><p>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.</p><p>When an item invokes a script, the script has access to some environment variables, such as:</p><divclass="codeBlockContainer_I0IT language-bash theme-code-block"><divclass="codeBlockContent_wNvx"style="color:#bfc7d5;background-color:#292d3e"><pretabindex="0"class="prism-code language-bash codeBlock_jd64 thin-scrollbar"><codeclass="codeBlockLines_mRuA"><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><buttontype="button"aria-label="Copy code to clipboard"title="Copy"class="copyButton_eDfN clean-btn"><spanclass="copyButtonIcons_W9eQ"aria-hidden="true"><svgclass="copyButtonIcon_XEyF"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_i9w9"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><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="codeBlockContainer_I0IT language-bash theme-code-block"><divclass="codeBlockContent_wNvx"style="color:#bfc7d5;background-color:#292d3e"><pretabindex="0"class="prism-code language-bash codeBlock_jd64 thin-scrollbar"><codeclass="codeBlockLines_mRuA"><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><buttontype="button"aria-label="Copy code to clipboard"title="Copy"class="copyButton_eDfN clean-btn"><spanclass="copyButtonIcons_W9eQ"aria-hidden="true"><svgclass="copyButtonIcon_XEyF"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_i9w9"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><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>Some events send additional information in the <code>$INFO</code> variable</p><p>All scripts are forced to terminate after 60 seconds and do not run while the system is sleeping. </p><h3class="anchor anchorWithStickyNavbar_mojV"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 a different application (see Trigger custom events). Items can also subscribe to these events for their script execution.</p><divclass="codeBlockContainer_I0IT language-bash theme-code-block"><divclass="codeBlockContent_wNvx"style="color:#bfc7d5;background-color:#292d3e"><pretabindex="0"class="prism-code language-bash codeBlock_jd64 thin-scrollbar"><codeclass="codeBlockLines_mRuA"><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><buttontype="button"aria-label="Copy code to clipboard"title="Copy"class="copyButton_eDfN clean-btn"><spanclass="copyButtonIcons_W9eQ"aria-hidden="true"><svgclass="copyButtonIcon_XEyF"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_i9w9"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><p>Optional: You can subscribe to the notifications sent to the NSDistributedNotificationCenter e.g.
the notification Spotify sends on track change: <em>com.spotify.client.PlaybackStateChanged</em> (<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 a bluetooth device connected, or disconnected: <em>com.apple.bluetooth.state</em> (<ahref="https://github.com/FelixKratz/SketchyBar/discussions/12#discussioncomment-1465761"target="_blank"rel="noopener noreferrer">example</a>)
to create more responsive items. Custom events that subscribe to NSDistributedNotificationCenter notifications will receive additional notification information in the <code>$INFO</code> variable if available.</p><h3class="anchor anchorWithStickyNavbar_mojV"id="triggering-custom-events">Triggering custom events<aclass="hash-link"href="#triggering-custom-events"title="Direct link to heading"></a></h3><p>This triggers a custom event that has been added before</p><divclass="codeBlockContainer_I0IT language-bash theme-code-block"><divclass="codeBlockContent_wNvx"style="color:#bfc7d5;background-color:#292d3e"><pretabindex="0"class="prism-code language-bash codeBlock_jd64 thin-scrollbar"><codeclass="codeBlockLines_mRuA"><spanclass="token-line"style="color:#bfc7d5"><spanclass="token plain">sketchybar --trigger </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">Optional: </span><spanclass="token operator"style="color:rgb(137, 221, 255)"><</span><spanclass="token plain">envvar</span><spanclass="token operator"style="color:rgb(137, 221, 255)">>=</span><spanclass="token operator"style="color:rgb(137, 221, 255)"><</span><spanclass="token plain">value</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">envvar</span><spanclass="token operator"style="color:rgb(137, 221, 255)">>=</span><spanclass="token operator"style="color:rgb(137, 221, 255)"><</span><spanclass="token plain">value</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><buttontype="button"aria-label="Copy code to clipboard"title="Copy"class="copyButton_eDfN clean-btn"><spanclass="copyButtonIcons_W9eQ"aria-hidden="true"><svgclass="copyButtonIcon_XEyF"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_i9w9"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><p>Optionaly you can add environment variables to the trigger command witch are passed to the script, e.g.:</p><divclass="codeBlockContainer_I0IT language-bash theme-code-block"><divclass="codeBlockContent_wNvx"style="color:#bfc7d5;background-color:#292d3e"><pretabindex="0"class="prism-code language-bash codeBlock_jd64 thin-scrollbar"><codeclass="codeBlockLines_mRuA"><spanclass="token-line"style="color:#bfc7d5"><spanclass="token plain">sketchybar --trigger demo </span><spanclass="token assign-left variable"style="color:rgb(191, 199, 213)">VAR</span><spanclass="token operator"style="color:rgb(137, 221, 255)">=</span><spanclass="token plain">Test</span><br></span></code></pre><buttontype="button"aria-label="Copy code to clipboard"title="Copy"class="copyButton_eDfN clean-btn"><spanclass="copyButtonIcons_W9eQ"aria-hidden="true"><svgclass="copyButtonIcon_XEyF"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_i9w9"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><p>will trigger the demo event and <code>$VAR</code> will be available as an environment variable in the scripts that this event invokes.
This could be used to link the powerful event system of yabai to sketchybar by triggering the custom action via a yabai event.</p><h3class="anchor anchorWithStickyNavbar_mojV"id="forcing-all-shell-scripts-to-run-and-the-bar-to-refresh">Forcing all shell scripts to run and the bar to refresh<aclass="hash-link"href="#forcing-all-shell-scripts-to-run-and-the-bar-to-refresh"title="Direct link to heading"></a></h3><divclass="codeBlockContainer_I0IT language-bash theme-code-block"><divclass="codeBlockContent_wNvx"style="color:#bfc7d5;background-color:#292d3e"><pretabindex="0"class="prism-code language-bash codeBlock_jd64 thin-scrollbar"><codeclass="codeBlockLines_mRuA"><spanclass="token-line"style="color:#bfc7d5"><spanclass="token plain">sketchybar --update</span><br></span></code></pre><buttontype="button"aria-label="Copy code to clipboard"title="Copy"class="copyButton_eDfN clean-btn"><spanclass="copyButtonIcons_W9eQ"aria-hidden="true"><svgclass="copyButtonIcon_XEyF"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_i9w9"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></article><navclass="pagination-nav docusaurus-mt-lg"aria-label="Docs pages navigation"><divclass="pagination-nav__item"><aclass="pagination-nav__link"href="/SketchyBar/config/popups"><divclass="pagination-nav__sublabel">Previous</div><divclass="pagination-nav__label">Popup Menus</div></a></div><divclass="pagination-nav__item pagination-nav__item--next"><aclass="pagination-nav__link"href="/SketchyBar/config/querying"><divclass="pagination-nav__sublabel">Next</div><divclass="pagination-nav__label">Querying Information</div></a></div></nav></div></div><divclass="col col--3"><divclass="tableOfContents_cNA8 thin-scrollbar theme-doc-toc-desktop"><ulclass="table-of-contents table-of-contents__left-border"><li><ahref="#events-and-scripting"class="table-of-contents__link toc-highlight">Events and Scripting</a><ul><li><ahref="#creating-custom-events"class="table-of-contents__link toc-highlight">Creating custom events</a></li><li><ahref="#triggering-custom-events"class="table-of-contents__link toc-highlight">Triggering custom events</a></li><li><ahref="#forcing-all-shell-scripts-to-run-and-the-bar-to-refresh"class="table-of-contents__link toc-highlight">Forcing all shell scripts to run and the bar to refresh</a></li></ul></li></ul></div></div></div></div></main></div></div></div>
