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. Six 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.

Workspaces

The workspaces widget shows each workspace and its apps from AeroSpace, yabai or OmniWM, and follows you as you switch. Without a window manager, it can show macOS Spaces. See Built-in widgets.

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.

Themes

Six themes ship with StableBar, alongside Built-in. Choose one during setup, cycle through them on your own bar with Try Themes…, or get more from the store. Save as Theme… turns your own look into one. See Themes.

Edit the bar in place

Choose Edit Bar in Place from the bar's right-click menu to arrange widgets on the bar itself: drag them between positions, remove them with − or add one with +. Changes save as you go, with undo. See Settings.

Any script is a widget

A widget can run any command that prints text or a JSON object, refresh on a timer or on events, and open a popup with graphs, lists and controls.

#!/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.

Widget store

Settings → Packages → Store lists widgets and themes from the StableBar store. Before anything runs, StableBar shows the commands, hosts and permissions a package uses. See Packages and the store.

Settings or JSON

Change content, appearance and behavior in Settings, with undo and redo, or edit the file it saves to. Your bar lives in ~/.config/stablebar/config.json: 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. See Settings and Configuration.

{
  "$schema": "https://raw.githubusercontent.com/Seb-GRAF/StableBar/main/stablebar.schema.json",
  "theme": { "id": "catppuccin" },
  "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" }
  ]
}

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. To remove StableBar, use Settings → General → Uninstall, which also turns off the menu bar auto-hide that StableBar turned on.

Documentation

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

Authors

StableBar is built by Sebastien Graf and Steve Mendes Reis, with help from everyone who has contributed.

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.