Configuration

Edit ~/.config/sbar/config.json. sbar reloads it when the file changes. If the file is missing, the bar shows the application owning the menu bar, a divider, and a clock. Removing the file restores that default bar. Invalid edits leave the last valid configuration in place; an invalid file at startup leaves the default bar in place. Inspect errors with sbar query --diagnostics. Valid reloads preserve unchanged native providers and refresh snapshots.

Run sbar validate to check the file without starting the bar. To check another file, use sbar validate --config /path/to/config.json. Invalid or missing files produce an error and a nonzero exit status. Validation never writes the file. Use sbar start --config /path/to/config.json to run with another configuration.

Save persistent changes in the configuration file. sbar never writes to the file or backs it up. For editor completion, copy config.schema.json beside your configuration and add "$schema": "config.schema.json" to the root object.

The Everyday bar includes native application icons, media shown only during playback, CPU and memory percentages, unread Mail counts, and connection and audio-device popovers. It uses text templates for labels, plus hover colours and minimum widths for its CPU and memory items. The floating bar has fewer items, inset edges, and rounded corners.

Example

Create ~/.config/sbar/config.json with a configuration such as:

{
  "schemaVersion": 1,
  "bar": {},
  "items": {
    "left": [
      { "id": "app", "type": "frontApplication" }
    ],
    "right": [
      { "id": "battery", "type": "battery" },
      { "id": "clock", "type": "datetime", "format": "HH:mm" }
    ]
  }
}

The root object requires schemaVersion, bar, and items. Only schemaVersion: 1 is supported. An empty bar uses the default bar settings; an empty items displays no items. Add an optional theme for bar and item appearance.

Use the shared text field to customise labels with provider values and conditional sections. Provider defaults apply when text is omitted.

Provider configuration blocks must match the item’s type. For example, an audioDevice block belongs on an audioDevice item. Validation also checks disabled items and children. Use sbar validate alongside editor schema checks to catch duplicate IDs and other constraints that depend on multiple values.

Bar settings

main selects the primary display. Use sbar query --displays to find connected display IDs and names.

The default floating window level keeps the bar above ordinary windows and below system notifications and the revealed menu bar. Explicit statusBar and screenSaver levels can cover notifications, especially when the menu bar auto-hides and banners overlap the bar.

Top placement uses the physical screen edge, sharing the system menu-bar area. Bottom placement respects the Dock’s visible work area. On notched displays, items avoid the cutout and the centre section sits immediately to its right.

The bar does not hide the system menu bar or reserve space for application windows. Set a gap in your window manager and adjust the bar’s margins to avoid overlap.

Space transitions

Panels follow display and Space changes. sbar uses a shared Space to keep panels visible during desktop transition animations. This uses private macOS SkyLight APIs, independently of the Spaces provider. If those APIs are unavailable or the shared Space cannot be created, the bar logs a warning and keeps its normal AppKit window behaviour.

Floating bar

For a floating bar, inset the panel and round its background:

{
  "schemaVersion": 1,
  "bar": {
    "height": 40,
    "shadow": true,
    "margin": { "top": 44, "left": 12, "right": 12 }
  },
  "theme": {
    "horizontalPadding": 16,
    "verticalPadding": 4,
    "cornerRadius": 12
  },
  "items": { "right": [{ "id": "clock", "type": "datetime", "format": "HH:mm" }] }
}

Margins shrink the area available to the bar. Top bars sit at the top of that area, and bottom bars sit at the bottom. Left and right margins control width independently. sbar limits excessive margins to leave at least one point of available space and reduces the height to fit. The top margin starts at the physical screen edge. Leave enough room for your display’s notch and menu bar. Notch avoidance stops once the panel is below the cutout. These settings reload automatically when the configuration file changes.

The theme’s verticalPadding and cornerRadius accept 0 to 48 points and default to zero. Padding sits inside bar.height. The rounded corners clip the content and background, whether you use the system material or a custom colour.

Shadows

Set bar.shadow to true to enable a shadow. Inset or rounded bars use the native macOS window shadow. macOS controls its colour, blur, and offset.

Square bars spanning the display’s full width use a soft 16-point fade below a top bar or above a bottom bar. The fade shortens at the screen edge. It uses extra transparent window space that passes clicks through, so the shadow does not change the configured bar height, content position, or mouse hit regions.

Shadow changes reload with the configuration, including changes to the margins, background, and corner radius.