StableBar

A native, configurable menu bar for macOS.
Themes, widgets and popups, set up in the app or in plain JSON.

Download · Website · User guide · Widget store · Examples

Features

• Native. Swift, AppKit and SwiftUI, with no web view or private window-server API, except in the opt-in macOS Spaces workspace source. One panel per display; workspace changes update the widgets in place instead of recreating windows.
• Guided setup. Pick a preset, a theme and a placement, and watch each choice on your real bar. Then edit the bar in place, in Settings or in JSON.
• Themes. Fifteen ship with the app and more come from the store. Save as Theme… turns your own look into one. Experimental Liquid Glass on macOS 26.
• Built-in widgets. Workspaces, app menus, the active app, clock, CPU and memory, network, battery, sound and calendar, without running a script.
• Any script is a widget. Print text or JSON from any language, refresh on a timer or on events, and open a popup with graphs, lists and controls.
• Window managers. Workspaces from AeroSpace, yabai or OmniWM. Without one, StableBar can keep windows and notifications clear of the bar.
• Every display. Notch-aware placement, widgets per kind of screen and a separate bar for each screen setup.
• Scriptable. The command line queries and edits the running bar and sends events from other tools.

Themes

The same bar in each theme that ships with StableBar. Choose one during setup, cycle through them on your own bar with Try Themes…, or get more from the store.

Popups

Any widget can open a popup. Build it from rows, columns, text, graphs, lists, buttons, sliders, toggles and search fields, filled with the widget's data. See Custom popups.

Settings

Change content, appearance and behavior without touching JSON. Settings saves to the same configuration file you can edit by hand, with undo and redo. See Settings.

Install

1. Download StableBar.dmg from the latest release.
2. Open it and drag StableBar to Applications.
3. Open StableBar. Setup walks you through a preset, a theme and a placement.

With Homebrew, brew install --cask seb-graf/tap/stablebar replaces the first two steps.

StableBar needs macOS 14 or later on Apple silicon. Releases update themselves; choose the Beta track in Settings → General → Updates to get betas. See Getting started.

Configure

Your bar lives in ~/.config/stablebar/config.json. Setup and Settings save to it, and you can edit it yourself: StableBar applies the file when you save it, and keeps the last working bar if a change is invalid. The JSON schema gives editors completion and validation.

{
  "$schema": "https://raw.githubusercontent.com/Seb-GRAF/StableBar/main/stablebar.schema.json",
  "theme": { "id": "rose-pine" },
  "widgets": [
    { "id": "spaces", "type": "workspaces", "position": "left" },
    { "id": "app", "type": "activeApp", "position": "left" },
    { "id": "power", "type": "battery", "position": "right" },
    { "id": "clock", "type": "clock", "position": "right", "format": "EEE d MMM  HH:mm" }
  ]
}

Write a widget

A widget can run any command that prints text or a JSON object:

#!/bin/sh
# ~/.config/stablebar/widgets/disk.sh
used=$(df -h / | awk 'NR == 2 { print $5 }')
printf '{"text":"%s","icon":"internaldrive"}' "$used"

{
  "id": "disk", "type": "script", "position": "right", "interval": 300,
  "command": "~/.config/stablebar/widgets/disk.sh"
}

Create a widget covers the output format, events and layouts. Share a widget as a package, or install others from the store in Settings → Packages.

Documentation

The user guide documents every feature and configuration option. Start with Getting started, or try one of the working setups in examples.

Contributing

Bug reports, ideas and pull requests are welcome. CONTRIBUTING.md explains how to build StableBar, run the tests and open a pull request. Report security issues privately, as described in SECURITY.md.

License

StableBar is available under the MIT License, including commercial use and redistribution.