<title>sxbar — wiki</title>
<style>
:root {
--bg: #f3f5f8;
--surface: #ffffff;
--surface2: #e9edf3;
--ink: #1a2029;
--muted: #5b6472;
--accent: #a8690a;
--accent2: #257587;
--border: rgba(20,30,45,0.11);
--code-ink: #2b3140;
--red: #b3372c;
--green: #2f7d4f;
--mono: "JetBrains Mono", ui-monospace, "SF Mono", "Cascadia Code", "Fira Code", Consolas, monospace;
--sans: -apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Arial, sans-serif;
--fs-3xl: clamp(1.9rem, 1.5rem + 1.6vw, 2.6rem);
--fs-2xl: 1.75rem;
--fs-xl: 1.375rem;
--fs-lg: 1.0625rem;
--fs-base: 1rem;
--fs-sm: 0.875rem;
--fs-xs: 0.75rem;
}
@media (prefers-color-scheme: dark) {
:root {
--bg: #12151c;
--surface: #1a1e27;
--surface2: #21262f;
--ink: #e4e9f0;
--muted: #8b93a3;
--accent: #e8a33d;
--accent2: #6fb3c2;
--border: rgba(255,255,255,0.09);
--code-ink: #d7dde6;
--red: #e0685c;
--green: #6fce93;
}
}
:root[data-theme="dark"] {
--bg: #12151c;
--surface: #1a1e27;
--surface2: #21262f;
--ink: #e4e9f0;
--muted: #8b93a3;
--accent: #e8a33d;
--accent2: #6fb3c2;
--border: rgba(255,255,255,0.09);
--code-ink: #d7dde6;
--red: #e0685c;
--green: #6fce93;
}
:root[data-theme="light"] {
--bg: #f3f5f8;
--surface: #ffffff;
--surface2: #e9edf3;
--ink: #1a2029;
--muted: #5b6472;
--accent: #a8690a;
--accent2: #257587;
--border: rgba(20,30,45,0.11);
--code-ink: #2b3140;
--red: #b3372c;
--green: #2f7d4f;
}
* { box-sizing: border-box; }
html { scroll-behavior: smooth; }
@media (prefers-reduced-motion: reduce) { html { scroll-behavior: auto; } }
body {
margin: 0;
background: var(--bg);
color: var(--ink);
font-family: var(--sans);
font-size: var(--fs-base);
line-height: 1.65;
-webkit-font-smoothing: antialiased;
}
a { color: var(--accent2); text-decoration: none; }
a:hover { text-decoration: underline; }
a:focus-visible, button:focus-visible, summary:focus-visible {
outline: 2px solid var(--accent2);
outline-offset: 2px;
border-radius: 2px;
}
h1, h2, h3, h4 {
font-family: var(--mono);
font-weight: 700;
text-wrap: balance;
letter-spacing: -0.01em;
color: var(--ink);
}
code, kbd, .mono { font-family: var(--mono); }
/* ---------- fake status-bar hero mockup ---------- */
.barmock {
display: flex;
align-items: center;
gap: 14px;
background: #000;
color: #7abccd;
font-family: var(--mono);
font-size: 0.8125rem;
padding: 7px 14px;
border-bottom: 1px solid var(--border);
}
.barmock .ws { display: flex; gap: 6px; }
.barmock .ws span {
padding: 2px 8px;
border-radius: 2px;
color: #7abccd;
}
.barmock .ws span.active { background: #7abccd; color: #000; }
.barmock .clock { color: #50fa7b; }
.barmock .spacer { flex: 1; }
.barmock .mods { display: flex; gap: 16px; }
.barmock .mods .bat { color: #ffb86c; }
.barmock .mods .vol { color: #ff79c6; }
.barmock .mods .cpu { color: #bd93f9; }
.barmock .mods .bt { color: #4a9eff; }
.barmock .mods .net { color: #2ee6d6; }
.barmock .ver { color: #444; padding-left: 6px; }
/* ---------- shell layout ---------- */
.shell {
display: grid;
grid-template-columns: 250px minmax(0, 1fr);
max-width: 1180px;
margin: 0 auto;
}
@media (max-width: 880px) {
.shell { grid-template-columns: 1fr; }
}
nav.toc {
position: sticky;
top: 0;
align-self: start;
height: 100vh;
overflow-y: auto;
padding: 28px 18px 40px 24px;
border-right: 1px solid var(--border);
font-family: var(--mono);
font-size: 0.8125rem;
}
@media (max-width: 880px) {
nav.toc {
position: static;
height: auto;
border-right: none;
border-bottom: 1px solid var(--border);
padding: 18px 20px;
}
}
nav.toc .brand {
display: flex;
align-items: baseline;
gap: 8px;
margin-bottom: 22px;
}
nav.toc .brand strong { font-size: 1rem; }
nav.toc .brand span { color: var(--muted); font-size: var(--fs-xs); }
nav.toc .group { margin-bottom: 20px; }
nav.toc .group h4 {
font-size: var(--fs-xs);
text-transform: uppercase;
letter-spacing: 0.08em;
color: var(--muted);
margin: 0 0 8px;
font-weight: 600;
}
nav.toc ul { list-style: none; margin: 0; padding: 0; }
nav.toc li { margin: 0; }
nav.toc a {
display: block;
color: var(--ink);
padding: 5px 8px;
margin: 0 -8px;
border-radius: 4px;
opacity: 0.72;
}
nav.toc a:hover { opacity: 1; background: var(--surface2); text-decoration: none; }
nav.toc a.active { opacity: 1; color: var(--accent); background: var(--surface2); }
main {
padding: 40px clamp(20px, 4vw, 56px) 100px;
min-width: 0;
}
.tagline {
color: var(--muted);
font-size: var(--fs-lg);
max-width: 62ch;
margin: 14px 0 0;
}
.toprow {
display: flex;
align-items: center;
justify-content: space-between;
gap: 16px;
flex-wrap: wrap;
}
.badges { display: flex; gap: 8px; flex-wrap: wrap; }
.badge {
font-family: var(--mono);
font-size: var(--fs-xs);
padding: 3px 9px;
border-radius: 20px;
border: 1px solid var(--border);
color: var(--muted);
}
section {
margin-top: 64px;
scroll-margin-top: 20px;
}
section h2 {
font-size: var(--fs-2xl);
margin: 0 0 6px;
padding-bottom: 12px;
border-bottom: 1px solid var(--border);
}
section > .lede {
color: var(--muted);
max-width: 68ch;
margin: 14px 0 26px;
}
h3 {
font-size: var(--fs-xl);
margin: 36px 0 10px;
}
h4 {
font-size: var(--fs-lg);
margin: 22px 0 8px;
}
p { max-width: 70ch; }
.eyebrow {
font-family: var(--mono);
font-size: var(--fs-xs);
text-transform: uppercase;
letter-spacing: 0.09em;
color: var(--accent);
font-weight: 700;
margin: 0 0 8px;
}
/* ---------- code blocks ---------- */
pre {
background: var(--surface);
border: 1px solid var(--border);
border-radius: 8px;
padding: 14px 16px;
overflow-x: auto;
font-family: var(--mono);
font-size: 0.8125rem;
line-height: 1.6;
color: var(--code-ink);
margin: 12px 0 20px;
}
pre .k { color: var(--accent); } /* directive keyword */
pre .s { color: var(--green); } /* quoted string */
pre .c { color: var(--muted); font-style: italic; } /* comment */
pre .v { color: var(--accent2); } /* value */
code.inline {
background: var(--surface2);
border: 1px solid var(--border);
border-radius: 4px;
padding: 0.1em 0.4em;
font-size: 0.875em;
color: var(--code-ink);
white-space: nowrap;
}
/* ---------- tables ---------- */
.twrap { overflow-x: auto; margin: 16px 0 24px; }
table {
border-collapse: collapse;
width: 100%;
min-width: 560px;
font-size: var(--fs-sm);
}
th, td {
text-align: left;
padding: 9px 14px;
border-bottom: 1px solid var(--border);
vertical-align: top;
}
th {
font-family: var(--mono);
font-size: var(--fs-xs);
text-transform: uppercase;
letter-spacing: 0.06em;
color: var(--muted);
font-weight: 600;
}
td.mono, th.mono { font-family: var(--mono); }
td code.inline { white-space: normal; }
tr:last-child td { border-bottom: none; }
.pill {
display: inline-block;
font-family: var(--mono);
font-size: var(--fs-xs);
padding: 2px 8px;
border-radius: 20px;
}
.pill.on { background: color-mix(in srgb, var(--green) 18%, transparent); color: var(--green); }
.pill.off { background: var(--surface2); color: var(--muted); }
.pill.req { background: color-mix(in srgb, var(--accent) 16%, transparent); color: var(--accent); }
/* ---------- cards / row-type grid ---------- */
.grid3 {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(210px, 1fr));
gap: 14px;
margin: 18px 0 26px;
}
.card {
background: var(--surface);
border: 1px solid var(--border);
border-radius: 10px;
padding: 16px 18px;
}
.card .eyebrow { margin-bottom: 6px; }
.card p { margin: 0; font-size: var(--fs-sm); color: var(--muted); }
.card h4 { margin: 0 0 6px; font-size: var(--fs-base); }
.note {
border-left: 3px solid var(--accent2);
background: color-mix(in srgb, var(--accent2) 8%, transparent);
padding: 10px 16px;
border-radius: 0 8px 8px 0;
font-size: var(--fs-sm);
margin: 16px 0;
max-width: 70ch;
}
.note strong { color: var(--accent2); }
footer {
border-top: 1px solid var(--border);
margin-top: 70px;
padding: 28px clamp(20px, 4vw, 56px);
color: var(--muted);
font-size: var(--fs-sm);
grid-column: 2;
}
@media (max-width: 880px) { footer { grid-column: 1; } }
::selection { background: color-mix(in srgb, var(--accent) 35%, transparent); }
.toggle-theme {
font-family: var(--mono);
font-size: var(--fs-xs);
background: var(--surface2);
border: 1px solid var(--border);
color: var(--ink);
border-radius: 20px;
padding: 5px 12px;
cursor: pointer;
}
</style>
<div class="barmock" aria-hidden="true">
<div class="ws"><span class="active">1</span><span>2</span><span>3</span></div>
<span class="clock"> 14:32:07</span>
<div class="spacer"></div>
<div class="mods">
<span class="bat"> 83%</span>
<span class="vol"> 47%</span>
<span class="cpu"> 22%</span>
<span class="bt"> On</span>
<span class="net"> wlp2s0</span>
</div>
<span class="ver">sxbar ver. 1.1</span>
</div>
<div class="shell">
<nav class="toc" id="toc">
<div class="brand">
<strong>sxbar</strong>
<span>wiki</span>
</div>
<div class="group">
<h4>Get started</h4>
<ul>
<li><a href="#overview">Overview</a></li>
<li><a href="#install">Install & build</a></li>
<li><a href="#quickstart">Quick start</a></li>
</ul>
</div>
<div class="group">
<h4>Appearance</h4>
<ul>
<li><a href="#bars">Global & bar options</a></li>
<li><a href="#workspaces">Workspaces & monitors</a></li>
</ul>
</div>
<div class="group">
<h4>Modules</h4>
<ul>
<li><a href="#modules">Built-in modules</a></li>
<li><a href="#taskbar">Taskbar</a></li>
<li><a href="#custom">Any name is a module</a></li>
<li><a href="#customize">Icons, colour, layout, clicks</a></li>
</ul>
</div>
<div class="group">
<h4>Floating popups</h4>
<ul>
<li><a href="#popups">Concept & triggers</a></li>
<li><a href="#popup-rows">Row types</a></li>
<li><a href="#popup-builtins">Built-in popups</a></li>
</ul>
</div>
<div class="group">
<h4>Reference</h4>
<ul>
<li><a href="#example">Full example config</a></li>
<li><a href="#reference">Directive reference</a></li>
</ul>
</div>
</nav>
<main>
<div class="toprow">
<div>
<h1 style="font-size:var(--fs-3xl); margin:0;">sxbar</h1>
<p class="tagline">A small, fast status bar for Xorg — one C99 binary, configured entirely
through a plain-text file. Workspaces, system stats, floating popups with
sliders and menus, all driven by shell commands you control.</p>
</div>
<button class="toggle-theme" id="themeToggle" type="button">toggle theme</button>
</div>
<div class="badges" style="margin-top:18px;">
<span class="badge">C99</span>
<span class="badge">Xlib + Xft + Xinerama</span>
<span class="badge">~36 KB binary</span>
<span class="badge">no daemon dependencies</span>
</div>
<section id="overview">
<h2>Overview</h2>
<p class="lede">sxbar renders a slim EWMH workspace switcher plus a row of
modules — clock, battery, volume, scripts you write yourself, anything you configure —
and can pop a floating slider or menu window out of any module.</p>
<p>Everything is controlled from a single config file, read from (in order)
<code class="inline">$XDG_CONFIG_HOME/sxbarc</code>,
<code class="inline">$XDG_CONFIG_HOME/sxbar/sxbarc</code>,
<code class="inline">~/.config/sxbarc</code>,
<code class="inline">~/.config/sxbar/sxbarc</code>, then a system-wide
fallback at <code class="inline">/usr/local/share/sxbarc</code>. There's
nothing to recompile to change modules, colours, icons, click actions or
popups — it's all config-file syntax of the form <code class="inline">key : value</code>.</p>
<div class="note"><strong>Multi-monitor</strong> is automatic: sxbar detects
screens via Xinerama and opens one bar per monitor, each with its own
workspace switcher filtered to windows actually on that screen.</div>
</section>
<section id="install">
<h2>Install & build</h2>
<p class="lede">Standard GNU make build. Needs Xlib, Xinerama and Xft
(with freetype2 headers) development packages, plus a C99 compiler.
Album art (<code class="inline">popup_image</code>, the
<code class="inline">media</code> module) needs no extra package —
image decoding is a vendored, public-domain single-header library
(<code class="inline">src/stb_image.h</code>) compiled straight into
the binary.</p>
<pre>git clone <this repo> sxbar
<span class="k">cd</span> sxbar
<span class="k">make</span>
<span class="k">sudo make install</span> <span class="c"># PREFIX defaults to /usr/local</span></pre>
<div class="twrap">
<table>
<thead><tr><th>Installed to</th><th>What</th></tr></thead>
<tbody>
<tr><td class="mono">$PREFIX/bin/sxbar</td><td>the binary</td></tr>
<tr><td class="mono">$PREFIX/share/man/man1/sxbar.1</td><td>man page</td></tr>
<tr><td class="mono">$PREFIX/share/sxbarc</td><td>fallback default config</td></tr>
<tr><td class="mono">$PREFIX/share/sxbar/scripts/</td><td>reference icon/demo scripts — copy to <code class="inline">~/.config/sxbar/scripts/</code> and edit your own copy</td></tr>
</tbody>
</table>
</div>
<p>Start it from your window manager's autostart / <code class="inline">.xinitrc</code>
with a plain <code class="inline">sxbar &</code>.</p>
</section>
<section id="quickstart">
<h2>Quick start</h2>
<p class="lede">Copy the shipped default config and enable a few modules to get oriented.</p>
<pre>mkdir -p ~/.config/sxbar
cp /usr/local/share/sxbarc ~/.config/sxbar/sxbarc</pre>
<pre><span class="k">font</span> : JetBrainsMono Nerd Font:size=10
<span class="k">background_colour</span> : #000000
<span class="k">foreground_colour</span> : #7abccd
<span class="k">module</span> : clock : <span class="v">true</span> : 1
<span class="k">module</span> : date : <span class="v">true</span> : 60
<span class="k">module</span> : battery : <span class="v">true</span> : 30
<span class="k">module</span> : volume : <span class="v">true</span> : 5
<span class="k">prefix</span> : clock : <span class="s">" "</span>
<span class="k">colour</span> : clock : <span class="v">#50fa7b</span></pre>
<p>Restart sxbar to pick up changes — it re-reads the config on startup, not live.</p>
</section>
<section id="bars">
<h2>Global & bar options</h2>
<p class="lede">Set once at the top of the config; apply to every bar unless noted.</p>
<div class="twrap">
<table>
<thead><tr><th class="mono">key</th><th>default</th><th>does</th></tr></thead>
<tbody>
<tr><td class="mono">height</td><td>19</td><td>bar height in px</td></tr>
<tr><td class="mono">bottom_bar</td><td>false</td><td>dock at the screen bottom instead of top</td></tr>
<tr><td class="mono">vertical_padding</td><td>0</td><td>gap between the bar and the screen edge</td></tr>
<tr><td class="mono">horizontal_padding</td><td>0</td><td>gap on both sides of the bar</td></tr>
<tr><td class="mono">text_padding</td><td>0</td><td>inner padding before the first workspace/module</td></tr>
<tr><td class="mono">border / border_width</td><td>false / 0</td><td>draw a border around the bar window</td></tr>
<tr><td class="mono">background_colour<br>foreground_colour<br>border_colour</td><td>#000000<br>#7abccd<br>#005577</td><td>hex (<code class="inline">#rrggbb</code>) or X colour name. These three don't support a trailing <code class="inline"># comment</code> on the same line — comment on its own line instead.</td></tr>
<tr><td class="mono">font</td><td>monospace:size=8</td><td>Xft font name, <code class="inline">Family:size=N[:style=Bold]</code>. Use a Nerd Font family here to render icon glyphs.</td></tr>
<tr><td class="mono">show_version<br>version_text</td><td>true<br>sxbar ver. 1.1</td><td>optional version string at the bar's right edge</td></tr>
<tr><td class="mono">secondary_bar</td><td>false</td><td>adds a second, modules-only bar on the opposite edge — see below</td></tr>
</tbody>
</table>
</div>
<h3>Secondary bar</h3>
<p>A second bar on the edge opposite <code class="inline">bottom_bar</code> — no
workspace switcher, no version text, just whichever modules you tag onto it.
Shares the primary bar's font/colours/height.</p>
<pre><span class="k">bottom_bar</span> : <span class="v">false</span>
<span class="k">secondary_bar</span> : <span class="v">true</span>
<span class="k">module</span> : battery : <span class="v">true</span> : 30
<span class="k">module</span> : volume : <span class="v">true</span> : 5
<span class="k">bar</span> : battery : <span class="v">secondary</span>
<span class="k">bar</span> : volume : <span class="v">secondary</span></pre>
<p><code class="inline">bar : module_name : primary|secondary</code> defaults to
<code class="inline">primary</code> — clock, date and the workspace switcher always
stay on the primary bar.</p>
</section>
<section id="workspaces">
<h2>Workspaces & monitors</h2>
<p class="lede">The workspace switcher reads standard EWMH properties, so it works
with any EWMH-compliant window manager — no sxbar-specific config needed.</p>
<ul>
<li>Workspace names come from <code class="inline">_NET_DESKTOP_NAMES</code>, the
current one from <code class="inline">_NET_CURRENT_DESKTOP</code>.</li>
<li>Each workspace pill shows up to 4 small boxes for windows on it — counted
per monitor, so a bar only reflects the windows actually on its own screen,
not every window across every screen.</li>
<li>One bar opens per monitor automatically (via Xinerama); each computes its
own <code class="inline">_NET_WM_STRUT_PARTIAL</code> so multiple bars don't
clobber each other's reserved screen edge.</li>
</ul>
<h3>Workspace icons</h3>
<pre><span class="k">workspace_icon</span> : name : <span class="s">"icon text"</span></pre>
<p>Replaces a workspace's displayed label — its
<code class="inline">_NET_DESKTOP_NAMES</code> string, typically a plain number
like <code class="inline">"1"</code> — with different text instead, e.g. a Nerd
Font glyph. Purely cosmetic: switching still targets the same underlying
desktop, only what's drawn on the pill changes. Needs a Nerd Font set via
<code class="inline">font</code> to render glyphs. Repeatable, one line per
workspace; any workspace without a matching line just shows its plain name,
same as always.</p>
<pre><span class="k">workspace_icon</span> : 1 : <span class="s">"<glyph>"</span>
<span class="k">workspace_icon</span> : 2 : <span class="s">"<glyph>"</span>
<span class="k">workspace_icon</span> : 3 : <span class="s">"<glyph>"</span></pre>
</section>
<section id="modules">
<h2>Built-in modules</h2>
<p class="lede">Enabled with <code class="inline">module : name : true|false : refresh_interval_seconds</code>.
Everything below is opt-in/opt-out by default as shown.</p>
<div class="twrap">
<table>
<thead><tr><th class="mono">module</th><th>shows</th><th>default</th><th>needs</th><th>popup</th></tr></thead>
<tbody>
<tr><td class="mono">clock</td><td>HH:MM:SS</td><td><span class="pill on">on</span></td><td>—</td><td>hover → open calendar</td></tr>
<tr><td class="mono">date</td><td>YYYY-MM-DD</td><td><span class="pill on">on</span></td><td>—</td><td>hover → open calendar</td></tr>
<tr><td class="mono">battery</td><td>charge %</td><td><span class="pill off">off</span></td><td><code class="inline">/sys/class/power_supply</code></td><td>hover → status + power-saver toggle</td></tr>
<tr><td class="mono">volume</td><td>volume %</td><td><span class="pill on">on</span></td><td><code class="inline">wpctl</code></td><td>hover → slider</td></tr>
<tr><td class="mono">cpu</td><td>usage %</td><td><span class="pill off">off</span></td><td><code class="inline">/proc/stat</code></td><td>hover → cpu / memory / per-core</td></tr>
<tr><td class="mono">brightness</td><td>brightness %</td><td><span class="pill off">off</span></td><td><span class="pill req">brightnessctl</span></td><td>hover → slider</td></tr>
<tr><td class="mono">bluetooth</td><td>On / Off</td><td><span class="pill off">off</span></td><td><span class="pill req">bluetoothctl</span></td><td>hover → power/scan/pair menu</td></tr>
<tr><td class="mono">usermenu</td><td>current username</td><td><span class="pill on">on</span></td><td><code class="inline">systemctl</code></td><td>hover → sleep/logout/shutdown</td></tr>
<tr><td class="mono">network</td><td>Online / Offline</td><td><span class="pill off">off</span></td><td><code class="inline">ip</code></td><td>hover → WiFi/Ethernet + IP</td></tr>
<tr><td class="mono">media</td><td>play/pause glyph + Artist - Title</td><td><span class="pill off">off</span></td><td><span class="pill req">playerctl</span>, curl for remote art</td><td>hover → album art + Previous/Play-Pause/Next</td></tr>
<tr><td class="mono">taskbar</td><td colspan="4">not like the others — see <a href="#taskbar">Taskbar</a> below</td></tr>
</tbody>
</table>
</div>
<p>Full detail on each popup is in <a href="#popup-builtins">Built-in popups</a> below.</p>
<div class="note"><strong>Not special-cased in the binary.</strong> Every
module — the ones above and any you write yourself — is resolved by name
to a script, purely from <code class="inline">module :</code> lines in
sxbarc; there's no separate "custom module" concept or directive. Each
name resolves (in order) to your own copy at
<code class="inline">~/.config/sxbar/scripts/<name>.sh</code>,
then the reference copy <code class="inline">make install</code> places
at <code class="inline">/usr/local/share/sxbar/scripts/<name>.sh</code>,
or a harmless no-op if neither exists. Copy any of them over and edit —
no recompile needed, and no sxbarc editing needed either to change a
module's popup content (e.g. adding a row to <code class="inline">usermenu</code>)
— see <a href="#custom">Reference scripts</a> below for the full list, and
"Any name is a module" in that section for writing your own.</div>
</section>
<section id="taskbar">
<h2>Taskbar</h2>
<p class="lede">Every module above renders one line of its own text.
<code class="inline">taskbar</code> doesn't: it shows one clickable segment per
window on the current workspace, so you can switch focus between them — the
motivating case being a window manager's monocle mode, where only one window
is visible at a time and there'd otherwise be no way to reach the others from
the bar. Typical setup is its own row on the <a href="#bars">secondary bar</a>,
directly beneath the primary status bar.</p>
<pre><span class="k">secondary_bar</span> : <span class="v">true</span>
<span class="k">module</span> : taskbar : <span class="v">true</span> : 1
<span class="k">bar</span> : taskbar : <span class="v">secondary</span></pre>
<div class="note"><strong>Needs <code class="inline">wmctrl</code></strong>, for both
listing windows and requesting focus — and a window manager that actually acts on
a <code class="inline">_NET_ACTIVE_WINDOW</code> client message (what
<code class="inline">wmctrl -i -a</code> sends to request focus). Checking sxwm's
own source (not just its advertised <code class="inline">_NET_SUPPORTED</code> list,
which does list it) showed that message was never handled — sxwm published
<code class="inline">_NET_ACTIVE_WINDOW</code> read-only to reflect its own focus,
but accepted no external requests to change it, and has no other IPC that could
either. <code class="inline">patches/net-active-window-mrjensk.patch</code> in the
sxwm repo adds that handling (reusing sxwm's own
<code class="inline">set_input_focus()</code>, the same function
<code class="inline">focus_next</code>/<code class="inline">focus_prev</code> use, so
monocle-mode raising behaves identically to switching focus with a keybind). Other
window managers may already support this out of the box — check yours.</div>
<p>It ignores its own <code class="inline">align</code> — as a fill module, it
always occupies whatever's left between the left- and right-aligned modules on
its bar, split into equal-width segments, rather than anchoring to one side. The
currently-focused window's segment is highlighted the same way the active
workspace pill is.</p>
</section>
<section id="custom">
<h2>Any name is a module</h2>
<p class="lede">There's no separate "custom module" directive. A module's
command is resolved purely by name — write a script, name it
<code class="inline"><name>.sh</code>, and it's a module.</p>
<pre><span class="k">module</span> : <span class="v">temp</span> : <span class="v">true</span> : 5</pre>
<p>...with <code class="inline">~/.config/sxbar/scripts/temp.sh</code> being e.g.:</p>
<pre><span class="c">#!/bin/sh</span>
sensors | grep <span class="s">'Package'</span> | awk <span class="s">'{print $4}'</span></pre>
<p>Resolution order: your own copy at
<code class="inline">~/.config/sxbar/scripts/<name>.sh</code> wins if it
exists, then the reference copy <code class="inline">make install</code> places
at <code class="inline">$PREFIX/share/sxbar/scripts/<name>.sh</code>, else
the module is a silent no-op — so a typo'd module name just shows nothing
rather than erroring. A module you write yourself takes every other
directive on this page too — <code class="inline">prefix</code>,
<code class="inline">colour</code>, <code class="inline">click</code>,
<code class="inline">popup</code>, and so on — exactly like any module sxbar
ships a script for; there's no distinction between the two once
<code class="inline">module :</code> has resolved a name to a script. If the
script understands a <code class="inline">menu</code> subcommand, it can also
declare its own popup, exactly like the reference scripts below — see the
note under the table.</p>
<h3>Reference scripts</h3>
<p>Every script sxbar ships with lives in <code class="inline">scripts/</code> and
installs to <code class="inline">$PREFIX/share/sxbar/scripts/</code> as a
reference copy — copy any of them to <code class="inline">~/.config/sxbar/scripts/</code>
and edit your own copy freely, no sxbarc changes needed for the name to keep
resolving to it.</p>
<p>One script per module, dispatched by subcommand where a module needs
more than one piece of output. Every one of them also answers a
<code class="inline">menu</code> subcommand — see the note below the table.</p>
<div class="twrap">
<table>
<thead><tr><th class="mono">script</th><th>subcommands</th></tr></thead>
<tbody>
<tr><td class="mono">clock.sh</td><td>bar text (default) · <code class="inline">menu</code></td></tr>
<tr><td class="mono">date.sh</td><td>bar text (default) · <code class="inline">menu</code></td></tr>
<tr><td class="mono">battery.sh</td><td><code class="inline">capacity</code> (bar, default) · <code class="inline">status</code> · <code class="inline">toggle-powersave</code> · <code class="inline">menu</code></td></tr>
<tr><td class="mono">volume.sh</td><td><code class="inline">get</code> (bar/slider, default) · <code class="inline">set VALUE</code> · <code class="inline">menu</code></td></tr>
<tr><td class="mono">brightness.sh</td><td><code class="inline">get</code> (bar/slider, default) · <code class="inline">set VALUE</code> · <code class="inline">menu</code></td></tr>
<tr><td class="mono">cpu.sh</td><td><code class="inline">usage [PREFIX]</code> (bar/popup, default) · <code class="inline">mem</code> · <code class="inline">cores</code> · <code class="inline">menu</code></td></tr>
<tr><td class="mono">bluetooth.sh</td><td><code class="inline">status</code> (bar, default) · <code class="inline">pair</code> · <code class="inline">menu</code></td></tr>
<tr><td class="mono">usermenu.sh</td><td>bar text (default) · <code class="inline">menu</code></td></tr>
<tr><td class="mono">network.sh</td><td><code class="inline">status</code> (bar, default) · <code class="inline">wifi</code> · <code class="inline">ethernet</code> · <code class="inline">menu</code></td></tr>
<tr><td class="mono">media.sh</td><td>bar text (default) · <code class="inline">track</code> · <code class="inline">art</code> · <code class="inline">prev</code> · <code class="inline">playpause</code> · <code class="inline">next</code> · <code class="inline">menu</code></td></tr>
</tbody>
</table>
</div>
<div class="note"><strong><code class="inline">menu</code></strong> is what
makes a module self-contained: run once at startup for every module
(whichever script its name resolves to), it prints that module's
<a href="#popup-builtins">popup definition</a> — the same
<code class="inline">popup</code>/<code class="inline">popup_item</code>/
<code class="inline">popup_info</code>/<code class="inline">popup_set</code>
directives sxbarc itself uses, minus the module-name field, since a
script only ever describes itself. Edit your own copy of e.g.
<code class="inline">usermenu.sh</code> to add, remove or reorder rows —
sxbarc's own directives can still override the result wholesale if you'd
rather keep everything in one config file (see
<a href="#popup-rows">Row types</a>).</div>
<p>Plus five standalone helpers:</p>
<div class="twrap">
<table>
<thead><tr><th class="mono">script</th><th>used as</th><th>does</th></tr></thead>
<tbody>
<tr><td class="mono">battery_icon.sh</td><td><code class="inline">prefix_cmd</code></td><td>picks a battery glyph by charge level, swaps to a bolt glyph while charging</td></tr>
<tr><td class="mono">volume_icon.sh</td><td><code class="inline">prefix_cmd</code></td><td>picks a volume glyph, mute-aware</td></tr>
<tr><td class="mono">demo_popup.sh</td><td><code class="inline">popup_item</code> / <code class="inline">popup_set</code></td><td>fires a desktop notification — a safe target for testing popup rows before wiring up real commands</td></tr>
<tr><td class="mono">demo_menu.sh</td><td><code class="inline">module : demo_menu : true : 999</code></td><td>self-declares one of every popup row type (text, image, button, slider, segmented buttons) via its own <code class="inline">menu</code> subcommand — a runnable reference, and a safe sandbox for testing hover/click/drag before building your own</td></tr>
<tr><td class="mono">startmenu.sh</td><td><code class="inline">module : startmenu : true : 3600</code></td><td>a hover popup of favorite apps as buttons — edit its <code class="inline">popup_item</code> lines to add/remove favorites, no sxbarc editing needed</td></tr>
</tbody>
</table>
</div>
<p><code class="inline">battery_icon.sh</code>, trimmed:</p>
<pre><span class="c">#!/bin/sh</span>
pct=$(printf <span class="s">'%s'</span> <span class="s">"$1"</span> | tr -dc <span class="s">'0-9'</span>)
status=$(cat /sys/class/power_supply/BAT*/status 2>/dev/null | head -n1)
<span class="k">if</span> [ <span class="s">"$status"</span> = <span class="s">"Charging"</span> ]; <span class="k">then</span>
printf <span class="s">'%s '</span> <span class="s">''</span> <span class="c"># bolt glyph</span>
exit 0
<span class="k">fi</span>
<span class="k">if</span> [ <span class="s">"$pct"</span> -ge 90 ]; <span class="k">then</span> printf <span class="s">'%s '</span> <span class="s">''</span>
<span class="k">elif</span> [ <span class="s">"$pct"</span> -ge 50 ]; <span class="k">then</span> printf <span class="s">'%s '</span> <span class="s">''</span>
<span class="k">else</span> printf <span class="s">'%s '</span> <span class="s">''</span>
<span class="k">fi</span></pre>
<p>The module's current output (e.g. <code class="inline">"83%"</code>) is passed in
as <code class="inline">$1</code>, shell-quoted — built-in commands don't expose
extra state like charging/muted beyond that string, so scripts needing it
re-check the system themselves.</p>
</section>
<section id="customize">
<h2>Icons, colour, layout, clicks</h2>
<p class="lede">These directives apply to any module, by name.</p>
<h3>Prefix / icon</h3>
<pre><span class="k">prefix</span> : module_name : <span class="s">"icon text"</span> <span class="c"># icon : ... is an accepted alias</span></pre>
<p>Static text prepended to a module's output. Needs a Nerd Font set via
<code class="inline">font</code> to render glyphs. Declare <code class="inline">prefix</code>
after the module's <code class="inline">module</code> line.</p>
<h4>Dynamic icon (<code class="inline">prefix_cmd</code>)</h4>
<pre><span class="k">prefix_cmd</span> : module_name : <span class="s">"command or script path"</span> <span class="c"># icon_cmd is an alias</span></pre>
<p>Runs a script instead of fixed text, so the icon can reflect live state (battery
charging, volume muted). Re-run every refresh, with the module's own current
output passed in as <code class="inline">$1</code>. Its stdout becomes the prefix
verbatim — include your own trailing space.</p>
<h3>Colour</h3>
<pre><span class="k">colour</span> : module_name : <span class="v">#rrggbb</span> <span class="c"># color : ... also works</span></pre>
<p>Overrides <code class="inline">foreground_colour</code> for one module.</p>
<h3>Width</h3>
<pre><span class="k">width</span> : module_name : <span class="v">min_pixels</span></pre>
<p>Reserves a minimum pixel width for the module's slot so neighbours don't
shift when its digit count changes (e.g. cpu going <code class="inline">9%</code> →
<code class="inline">16%</code> → <code class="inline">100%</code>). Text is
never truncated — wider values just use their natural width.</p>
<h3>Max width (scrolling / marquee text)</h3>
<pre><span class="k">max_width</span> : module_name : <span class="v">max_pixels</span></pre>
<p>The opposite of <code class="inline">width</code> above: caps a module's slot
at this many pixels. Text that fits draws as normal; text wider than the cap
scrolls left within that fixed width instead of stretching the bar — handy for
anything with unpredictable-length output, like <code class="inline">media</code>'s
"Artist - Title". sxbar only redraws faster than its usual once-a-second cadence
while something is actually scrolling, so this costs nothing when nothing
overflows.</p>
<pre><span class="k">max_width</span> : media : <span class="v">220</span></pre>
<p>This is a bar-level directive; a popup's own text rows (e.g.
<code class="inline">media</code>'s track title) scroll the same way
automatically whenever the popup also has an image, slider or button-row
to anchor its width — no separate config needed there, see
<a href="#popup-rows">Row types</a>.</p>
<h3>Alignment</h3>
<pre><span class="k">align</span> : module_name : <span class="v">left|center|right</span> <span class="c"># default: right</span></pre>
<p>Three independent groups per bar: left continues on from the workspace
switcher, center is centered across the full bar width, right is anchored
before <code class="inline">version_text</code>.</p>
<h3>icon_only</h3>
<pre><span class="k">icon_only</span> : module_name : <span class="v">true|false</span></pre>
<p>Shows only the prefix/icon, hiding the module's own text entirely. The
command, refresh interval and any popup keep running exactly as normal —
only the rendered bar text changes. Needs a <code class="inline">prefix</code>
or <code class="inline">prefix_cmd</code> set, or there's nothing left to show.</p>
<h3>Click & scroll</h3>
<pre><span class="k">click</span> : module_name : <span class="s">"command"</span>
<span class="k">scroll_up</span> : module_name : <span class="s">"command"</span>
<span class="k">scroll_down</span> : module_name : <span class="s">"command"</span></pre>
<pre><span class="k">click</span> : volume : <span class="s">"pavucontrol"</span>
<span class="k">scroll_up</span> : volume : <span class="s">"wpctl set-volume --limit 1.0 @DEFAULT_AUDIO_SINK@ 5%+"</span>
<span class="k">scroll_down</span> : volume : <span class="s">"wpctl set-volume @DEFAULT_AUDIO_SINK@ 5%-"</span></pre>
<p>Runs detached (double-fork) so sxbar never blocks. If a module also has a
<code class="inline">popup</code> with a <code class="inline">click</code>
trigger, the popup takes over left-click and <code class="inline">click</code>
is ignored for it — <code class="inline">scroll_up</code>/<code class="inline">scroll_down</code>
still work independently either way.</p>
</section>
<section id="popups">
<h2>Floating popups</h2>
<p class="lede">A module can open a small floating (override-redirect) window
instead of — or as well as — running a plain <code class="inline">click</code>
command. Only one popup is open at a time.</p>
<pre><span class="k">popup</span> : module_name : <span class="v">hover|click</span> : <span class="v">buttons|slider</span></pre>
<p>The third field only decides whether the module has a popup at all these
days — <code class="inline">popup_item</code>/<code class="inline">popup_info</code>/<code class="inline">popup_set</code>
decide what's actually in it, in any combination, so either word works there.</p>
<div class="grid3">
<div class="card">
<div class="eyebrow">hover</div>
<h4>Opens on mouse-over</h4>
<p>Reveals the popup while the pointer is over the module; closes when the
pointer leaves both the module and the popup. Every built-in popup uses this.</p>
</div>
<div class="card">
<div class="eyebrow">click</div>
<h4>Opens on left-click</h4>
<p>Toggles on click; closes again on a second click, or on clicking
anywhere else — like an ordinary dropdown menu.</p>
</div>
</div>
<div class="note">Hovering only <em>reveals</em> a menu — an actual click on a
button row is still needed to run anything. A hover-triggered
<code class="inline">usermenu</code> doesn't make "Shut down" any easier to
trigger by accident.</div>
</section>
<section id="popup-rows">
<h2>Row types</h2>
<p class="lede">A popup is a list of rows. Text, button, slider, image and
segmented-button rows all mix freely in the same popup.</p>
<div class="grid3">
<div class="card">
<div class="eyebrow">text</div>
<h4>popup_info</h4>
<p>Purely informational, not clickable at all. Label is a shell command's
output, re-run fresh every time the popup opens (e.g. current IP).</p>
</div>
<div class="card">
<div class="eyebrow">button</div>
<h4>popup_item</h4>
<p>Runs its own command on click; the popup stays open. Label is fixed
text, set once.</p>
</div>
<div class="card">
<div class="eyebrow">button</div>
<h4>popup_live_item</h4>
<p>Same as <code class="inline">popup_item</code>, but the label is a
shell command's output instead of fixed text, re-run fresh every time
the popup opens (like <code class="inline">popup_info</code>) — still
clickable, its own click command spawns independently of the label.
Use this for a single button that shows its own current state, e.g.
"Lid-suspend: OFF" that toggles when clicked.</p>
</div>
<div class="card">
<div class="eyebrow">slider</div>
<h4>popup_set</h4>
<p>Draggable 0–100% track; dragging doesn't close the popup. Starting
position comes from the module's own command output.</p>
</div>
<div class="card">
<div class="eyebrow">image</div>
<h4>popup_image</h4>
<p>Renders an image file, e.g. album art. Command's stdout is a path to a
local image, re-run fresh every popup open, scaled to fit a 160px box
by default — override per module with
<code class="inline">popup_image_size</code>. Not clickable. No extra
build dependency needed. Anchors the popup's width — any text row in
the same popup is capped to it and scrolls instead of stretching the
popup wider than the image.</p>
</div>
<div class="card">
<div class="eyebrow">buttons</div>
<h4>popup_buttons</h4>
<p>One row split into N equal-width button segments side by side (e.g.
media transport controls), instead of N stacked full-width
<code class="inline">popup_item</code> rows. Each segment runs its own
command on click; the popup stays open.</p>
</div>
</div>
<pre><span class="k">popup_item</span> : module_name : <span class="s">"Label"</span> : <span class="s">"command"</span> <span class="c"># button row, repeatable</span>
<span class="k">popup_live_item</span> : module_name : <span class="s">"label command"</span> : <span class="s">"command"</span> <span class="c"># button row, label re-run on every open</span>
<span class="k">popup_info</span> : module_name : <span class="s">"shell command"</span> <span class="c"># text row, repeatable</span>
<span class="k">popup_image</span> : module_name : <span class="s">"shell command"</span> <span class="c"># image row, stdout = path to an image file</span>
<span class="k">popup_image_size</span> : module_name : pixels <span class="c"># image row box size, default 160</span>
<span class="k">popup_buttons</span> : module_name : <span class="s">"L1"</span> : <span class="s">"cmd1"</span> : <span class="s">"L2"</span> : <span class="s">"cmd2"</span> ... <span class="c"># one row, N button segments</span>
<span class="k">popup_set</span> : module_name : <span class="s">"command"</span> <span class="c"># slider row, receives new value as $1 (e.g. "45%")</span></pre>
<p>The first <code class="inline">popup_item</code>/<code class="inline">popup_live_item</code>/
<code class="inline">popup_info</code>/
<code class="inline">popup_image</code>/<code class="inline">popup_buttons</code> line for
a module replaces its built-in default rows (if any, including a
<code class="inline">popup_set</code> slider row) — later lines append. Add
<code class="inline">popup_set</code> again afterwards if you cleared a built-in
slider this way and still want it back.</p>
<p>A module script's own <code class="inline">menu</code> subcommand can emit
<code class="inline">popup_live_item</code> the same way (no module-name field,
same as its other popup directives):</p>
<pre><span class="k">popup_live_item</span> : <span class="s">"~/.config/sxbar/scripts/lidsuspend.sh status"</span> : <span class="s">"~/.config/sxbar/scripts/lidsuspend.sh toggle"</span></pre>
<p>The label command's output becomes the button text on every popup open
(e.g. <code class="inline">"Lid-suspend: OFF"</code>), and clicking it runs the
second command regardless of what the label currently says.</p>
<p>Example combining all five on one module (<code class="inline">mymodule</code>
resolving to your own <code class="inline">~/.config/sxbar/scripts/mymodule.sh</code>):</p>
<pre><span class="k">module</span> : mymodule : <span class="v">true</span> : 5
<span class="k">popup</span> : mymodule : <span class="v">hover</span> : <span class="v">buttons</span>
<span class="k">popup_info</span> : mymodule : <span class="s">"echo 'status: '$(whoami)"</span>
<span class="k">popup_image</span> : mymodule : <span class="s">"echo /path/to/icon.png"</span>
<span class="k">popup_buttons</span> : mymodule : <span class="s">"⏮"</span> : <span class="s">"mymodule-ctl prev"</span> : <span class="s">"⏭"</span> : <span class="s">"mymodule-ctl next"</span>
<span class="k">popup_item</span> : mymodule : <span class="s">"Restart"</span> : <span class="s">"systemctl --user restart myservice"</span>
<span class="k">popup_set</span> : mymodule : <span class="s">"myservice-set-level"</span></pre>
<p>Or skip the sxbarc overrides entirely and declare the same popup from
<code class="inline">mymodule.sh</code> itself via its <code class="inline">menu</code>
subcommand — see <a href="#custom">Any name is a module</a> above and
<code class="inline">scripts/demo_menu.sh</code> for a runnable example of exactly this.</p>
</section>
<section id="popup-builtins">
<h2>Built-in popups</h2>
<p class="lede">What each built-in module's popup contains by default. This
content isn't hardcoded in the binary — it's each module's own
<code class="inline"><script> menu</code> output (see
<a href="#custom">Any name is a module</a>), shown below as the
equivalent sxbarc directives for reference. Edit the script directly to
change these, or override wholesale from sxbarc with the directives
above — either works, since the first <code class="inline">popup_item</code>/
<code class="inline">popup_info</code> line for a module always replaces
its current rows regardless of where they came from.</p>
<h3>clock · date — open calendar</h3>
<pre><span class="k">popup </span>: clock : <span class="v">hover</span> : <span class="v">buttons</span>
<span class="k">popup_item </span>: clock : <span class="s">"Open calendar"</span> : <span class="s">"gsimplecal"</span>
<span class="k">popup </span>: date : <span class="v">hover</span> : <span class="v">buttons</span>
<span class="k">popup_item </span>: date : <span class="s">"Open calendar"</span> : <span class="s">"gsimplecal"</span></pre>
<p>Same action on both, since clock and date are usually shown next to each other.</p>
<h3>battery — status + power-saver toggle</h3>
<pre><span class="k">popup </span>: battery : <span class="v">hover</span> : <span class="v">buttons</span>
<span class="k">popup_info </span>: battery : <span class="s">"~/.config/sxbar/scripts/battery.sh status"</span>
<span class="k">popup_item </span>: battery : <span class="s">"Toggle power saver"</span> : <span class="s">"~/.config/sxbar/scripts/battery.sh toggle-powersave"</span></pre>
<p>The status row (state, time remaining, health) needs <code class="inline">upower</code>;
the toggle needs <code class="inline">power-profiles-daemon</code> — both beyond the
plain <code class="inline">/sys/class/power_supply</code> read the bar text itself uses.</p>
<h3>brightness · volume — slider</h3>
<pre><span class="k">popup </span>: brightness : <span class="v">hover</span> : <span class="v">slider</span>
<span class="k">popup_set </span>: brightness : <span class="s">"~/.config/sxbar/scripts/brightness.sh set"</span>
<span class="k">popup </span>: volume : <span class="v">hover</span> : <span class="v">slider</span>
<span class="k">popup_set </span>: volume : <span class="s">"~/.config/sxbar/scripts/volume.sh set"</span></pre>
<h3>cpu — three status rows</h3>
<p>Fresh CPU sample, memory line, and a per-core breakdown (two
<code class="inline">/proc/stat</code> samples 0.2s apart, paired up by
position via an awk array — no process substitution, since
<code class="inline">/bin/sh</code> may be <code class="inline">dash</code>).
One script, <code class="inline">cpu.sh</code>, handles all three via subcommand.</p>
<pre><span class="k">popup </span>: cpu : <span class="v">hover</span> : <span class="v">buttons</span>
<span class="k">popup_info </span>: cpu : <span class="s">"~/.config/sxbar/scripts/cpu.sh usage 'CPU: '"</span>
<span class="k">popup_info </span>: cpu : <span class="s">"~/.config/sxbar/scripts/cpu.sh mem"</span>
<span class="k">popup_info </span>: cpu : <span class="s">"~/.config/sxbar/scripts/cpu.sh cores"</span></pre>
<h3>bluetooth — power / scan / pair</h3>
<pre><span class="k">popup </span>: bluetooth : <span class="v">hover</span> : <span class="v">buttons</span>
<span class="k">popup_item </span>: bluetooth : <span class="s">"Turn on"</span> : <span class="s">"bluetoothctl power on"</span>
<span class="k">popup_item </span>: bluetooth : <span class="s">"Turn off"</span> : <span class="s">"bluetoothctl power off"</span>
<span class="k">popup_item </span>: bluetooth : <span class="s">"Search for devices"</span> : <span class="s">"bluetoothctl --timeout 10 scan on"</span>
<span class="k">popup_item </span>: bluetooth : <span class="s">"Pair last found device"</span> : <span class="s">"~/.config/sxbar/scripts/bluetooth.sh pair"</span></pre>
<p>The first three are plain passthrough commands (no logic to extract into a
script); "pair" has real parsing/control flow, so it's the one that's scripted.
No interactive device list — it targets whichever device
<code class="inline">bluetoothctl devices</code> saw most recently.</p>
<h3>usermenu — sleep / log out / shut down</h3>
<pre><span class="k">popup </span>: usermenu : <span class="v">hover</span> : <span class="v">buttons</span>
<span class="k">popup_item </span>: usermenu : <span class="s">"Sleep"</span> : <span class="s">"systemctl suspend"</span>
<span class="k">popup_item </span>: usermenu : <span class="s">"Log out"</span> : <span class="s">"pkill sxwm"</span>
<span class="k">popup_item </span>: usermenu : <span class="s">"Shut down"</span> : <span class="s">"systemctl poweroff"</span></pre>
<div class="note">The default logout command is <code class="inline">pkill <your-wm></code>
— minimal window managers without a session manager have no external way to
trigger their own quit keybind. Simplest fix: edit the <code class="inline">pkill sxwm</code>
line directly in your own copy of <code class="inline">usermenu.sh</code> for your
WM/session — or override the <code class="inline">"Log out"</code> row's command
from sxbarc as shown above if you'd rather keep it in your config file.</div>
<h3>network — WiFi / Ethernet status</h3>
<p>Bar text is <code class="inline">Online</code>/<code class="inline">Offline</code>
based on whether a default route exists. Popup has two informational rows: first
interface with a <code class="inline">/sys/class/net/<if>/wireless</code>
directory for WiFi, first non-virtual <code class="inline">ARPHRD_ETHER</code>
interface for Ethernet — each showing its IPv4 address or "disconnected".</p>
<pre><span class="k">popup </span>: network : <span class="v">hover</span> : <span class="v">buttons</span>
<span class="k">popup_info </span>: network : <span class="s">"~/.config/sxbar/scripts/network.sh wifi"</span>
<span class="k">popup_info </span>: network : <span class="s">"~/.config/sxbar/scripts/network.sh ethernet"</span></pre>
<h3>media — album art + transport controls</h3>
<p>Bar text is a play/pause glyph plus <code class="inline">Artist - Title</code>,
via <code class="inline">playerctl</code> (controls whichever player it considers
active — most players speak MPRIS2 automatically: Spotify, VLC, mpv, browser
tabs, etc.). The popup's image row resolves <code class="inline">mpris:artUrl</code>:
a <code class="inline">file://</code> path is used directly; an
<code class="inline">http(s)://</code> one is downloaded once and cached under
<code class="inline">$XDG_CACHE_HOME/sxbar-media-art/</code> (needs
<code class="inline">curl</code>). The transport buttons are one
<code class="inline">popup_buttons</code> row (step-backward/play/step-forward
Nerd Font glyphs, U+F048/U+F04B/U+F051 — shown as
<code class="inline"><...></code> placeholders below since they render as
tofu without that font) rather than three stacked rows.</p>
<pre><span class="k">popup </span>: media : <span class="v">hover</span> : <span class="v">buttons</span>
<span class="k">popup_image </span>: media : <span class="s">"~/.config/sxbar/scripts/media.sh art"</span>
<span class="k">popup_info </span>: media : <span class="s">"~/.config/sxbar/scripts/media.sh track"</span>
<span class="k">popup_buttons </span>: media : <span class="s">"<step-backward>"</span> : <span class="s">"~/.config/sxbar/scripts/media.sh prev"</span> : <span class="s">"<play>"</span> : <span class="s">"~/.config/sxbar/scripts/media.sh playpause"</span> : <span class="s">"<step-forward>"</span> : <span class="s">"~/.config/sxbar/scripts/media.sh next"</span></pre>
<p>Bigger album art? Add
<code class="inline">popup_image_size : media : 220</code> alongside the
lines above — any pixel size, default is 160.</p>
</section>
<section id="example">
<h2>Full example config</h2>
<p class="lede">A config combining most of the directives on this page.</p>
<pre><span class="c"># appearance</span>
<span class="k">height</span> : 20
<span class="k">bottom_bar</span> : <span class="v">false</span>
<span class="k">vertical_padding</span> : 5
<span class="k">horizontal_padding</span> : 5
<span class="k">background_colour</span> : #000000
<span class="k">foreground_colour</span> : #7abccd
<span class="k">font</span> : JetBrainsMono Nerd Font:size=10
<span class="c"># modules</span>
<span class="k">module</span> : clock : <span class="v">true</span> : 1
<span class="k">module</span> : date : <span class="v">true</span> : 60
<span class="k">module</span> : battery : <span class="v">true</span> : 30
<span class="k">module</span> : volume : <span class="v">true</span> : 5
<span class="k">module</span> : cpu : <span class="v">true</span> : 3
<span class="k">module</span> : network : <span class="v">true</span> : 10
<span class="k">module</span> : usermenu : <span class="v">true</span> : 300
<span class="c"># icons + colours</span>
<span class="k">prefix</span> : clock : <span class="s">" "</span>
<span class="k">prefix</span> : network : <span class="s">" "</span>
<span class="k">colour</span> : clock : #50fa7b
<span class="k">colour</span> : battery : #ffb86c
<span class="k">colour</span> : volume : #ff79c6
<span class="k">colour</span> : network : #2ee6d6
<span class="c"># layout</span>
<span class="k">align</span> : clock : <span class="v">center</span>
<span class="k">width</span> : battery : 48
<span class="k">width</span> : volume : 48
<span class="k">icon_only</span> : network : <span class="v">true</span>
<span class="c"># actions</span>
<span class="k">scroll_up</span> : volume : <span class="s">"wpctl set-volume --limit 1.0 @DEFAULT_AUDIO_SINK@ 5%+"</span>
<span class="k">scroll_down</span> : volume : <span class="s">"wpctl set-volume @DEFAULT_AUDIO_SINK@ 5%-"</span>
<span class="c"># override the default logout command</span>
<span class="k">popup_item</span> : usermenu : <span class="s">"Sleep"</span> : <span class="s">"systemctl suspend"</span>
<span class="k">popup_item</span> : usermenu : <span class="s">"Log out"</span> : <span class="s">"loginctl terminate-session $XDG_SESSION_ID"</span>
<span class="k">popup_item</span> : usermenu : <span class="s">"Shut down"</span> : <span class="s">"systemctl poweroff"</span>
<span class="c"># a module you wrote yourself (~/.config/sxbar/scripts/mem.sh)</span>
<span class="k">module</span> : mem : <span class="v">true</span> : 10
<span class="k">prefix</span> : mem : <span class="s">" "</span></pre>
</section>
<section id="reference">
<h2>Directive reference</h2>
<p class="lede">Every config key, at a glance.</p>
<div class="twrap">
<table>
<thead><tr><th class="mono">directive</th><th>syntax</th></tr></thead>
<tbody>
<tr><td class="mono">module</td><td class="mono">module : name : true|false : interval</td></tr>
<tr><td class="mono">prefix</td><td class="mono">prefix : name : "text"</td></tr>
<tr><td class="mono">prefix_cmd</td><td class="mono">prefix_cmd : name : "command"</td></tr>
<tr><td class="mono">icon_only</td><td class="mono">icon_only : name : true|false</td></tr>
<tr><td class="mono">colour</td><td class="mono">colour : name : #rrggbb</td></tr>
<tr><td class="mono">width</td><td class="mono">width : name : min_pixels</td></tr>
<tr><td class="mono">align</td><td class="mono">align : name : left|center|right</td></tr>
<tr><td class="mono">bar</td><td class="mono">bar : name : primary|secondary</td></tr>
<tr><td class="mono">click</td><td class="mono">click : name : "command"</td></tr>
<tr><td class="mono">scroll_up / scroll_down</td><td class="mono">scroll_up : name : "command"</td></tr>
<tr><td class="mono">popup</td><td class="mono">popup : name : hover|click : buttons|slider</td></tr>
<tr><td class="mono">popup_item</td><td class="mono">popup_item : name : "Label" : "command"</td></tr>
<tr><td class="mono">popup_info</td><td class="mono">popup_info : name : "shell command"</td></tr>
<tr><td class="mono">popup_image</td><td class="mono">popup_image : name : "shell command"</td></tr>
<tr><td class="mono">popup_image_size</td><td class="mono">popup_image_size : name : pixels</td></tr>
<tr><td class="mono">popup_set</td><td class="mono">popup_set : name : "command"</td></tr>
<tr><td class="mono">height / bottom_bar / *_padding / border*</td><td>global bar geometry — see <a href="#bars">Global & bar options</a></td></tr>
<tr><td class="mono">background_colour / foreground_colour / border_colour / font</td><td>global appearance</td></tr>
<tr><td class="mono">show_version / version_text</td><td>global</td></tr>
<tr><td class="mono">secondary_bar</td><td class="mono">secondary_bar : true|false</td></tr>
<tr><td class="mono">workspace_icon</td><td class="mono">workspace_icon : name : "icon text"</td></tr>
</tbody>
</table>
</div>
</section>
</main>
<footer>
sxbar — the simple, yet powerful, status bar for Xorg. ~36 KB binary, no daemon
dependencies beyond Xlib/Xft/Xinerama.
</footer>
</div>
<script>
(function () {
var toggle = document.getElementById('themeToggle');
var root = document.documentElement;
toggle.addEventListener('click', function () {
var current = root.getAttribute('data-theme');
var prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
var effectiveDark = current ? current === 'dark' : prefersDark;
root.setAttribute('data-theme', effectiveDark ? 'light' : 'dark');
});
var links = Array.prototype.slice.call(document.querySelectorAll('nav.toc a'));
var sections = links.map(function (a) {
return document.querySelector(a.getAttribute('href'));
});
function onScroll() {
var pos = window.scrollY + 100;
var activeIdx = 0;
sections.forEach(function (sec, i) {
if (sec && sec.offsetTop <= pos) activeIdx = i;
});
links.forEach(function (a, i) {
a.classList.toggle('active', i === activeIdx);
});
}
document.addEventListener('scroll', onScroll, { passive: true });
onScroll();
})();
</script>