Every provider uses the same item structure. Start with id and type, then add the settings listed on its page. Shared styling, actions, and refresh controls are available to every provider. Use text templates to customise displayed labels; provider text settings below describe the default presentation.
Provider reference
| Provider | Updates | Dedicated configuration |
|---|---|---|
| Date and time | Every second | format, dateStyle, timeStyle |
| Front application | Native events | frontApplication block |
| Battery | Native events | battery block |
| Volume | Native events | volume block |
| Audio devices | Native events / 2-second retries when unavailable | audioDevice block |
| 30-second polling | - | |
| Network | Native events | network block |
| VPN | Native events / 2-second retries when unavailable | vpn block |
| Bluetooth | Native events / 2-second retries when unavailable | bluetooth block |
| CPU | 2-second sampling | cpu block |
| Memory | 2-second sampling | memory block |
| Disk | 2-second sampling | disk block |
| Throughput | 2-second sampling | throughput block |
| Media | Playback notifications | media block |
| Spaces | Native events | spaces block |
| AeroSpace | 2-second polling / fresh triggers | aerospace block |
| Yabai | 2-second polling / fresh triggers | yabai block |
| Shell command | Startup / trigger / interval | command block |
| Process plugin | Process stream | plugin block |
Layout items
These compose the bar rather than collect system data. See shared item options for containers and overflow.
| Type | Configuration | Behaviour |
|---|---|---|
text | text | Static text or a template using id and value; empty when omitted. |
group | children | Inline children, nesting up to eight levels. |
popup | text, children | Click to reveal children; label defaults to the item ID unless overridden. |
divider | Shared styling | Vertical separator. |
spacer | No dedicated options | Flexible empty space. |
Where the options differ
- Date and time supports localised styles and custom patterns. Front application follows the application owning the menu bar and can show its native icon alongside its name or on its own.
- Battery and Volume provide state symbols and colours.
- The Audio devices provider shows the default output or input device name. It supports custom labels, symbols, and colours, and can hide missing devices while keeping read errors visible.
- Mail shows Apple Mail’s combined inbox unread count. It needs Automation permission and a running Mail app, and uses shared item settings only.
- Network supports custom labels and connection-type filtering, including Wi-Fi.
- VPN lists registered service names and connection states, with custom labels, symbols, and colours. It can hide the item when disconnected.
- Bluetooth shows power state and connected device names, with custom labels, symbols, and colours. It can hide the item when no devices are connected while keeping access errors visible.
- CPU supports per-item smoothing and usage thresholds. Memory offers used bytes, percentage, or used/total values. Disk supports volume paths, capacity formats, and free-space thresholds.
- Throughput supports interface selection, byte or bit rates, and smoothing. Media supports player selection, metadata visibility, playback state icons, and hiding every state except playing.
- Spaces, AeroSpace, and Yabai support focused or per-display lists. Text loops customise each entry while retaining its colour and emphasis; Yabai uses its configured Space labels by default. Workspace providers have no built-in switching controls.
- Shell command captures a completed result. Process plugin streams updates. Both support structured JSON output, state appearance, and error policies.