Appearance

The optional top-level theme sets bar appearance and default item styling. Each item’s style overrides individual theme fields. Omitted or null fields inherit; explicit zero padding and transparent colours override inherited values.

Example

{
  "schemaVersion": 1,
  "bar": {},
  "theme": {
    "background": "#18202EEE",
    "horizontalPadding": 12,
    "itemSpacing": 8,
    "itemStyle": {
      "tint": "#E5E9F0",
      "fontSize": 13,
      "fontWeight": "medium",
      "horizontalPadding": 6,
      "verticalPadding": 2,
      "cornerRadius": 4
    }
  },
  "items": {
    "right": [
      {
        "id": "clock",
        "type": "datetime",
        "symbol": "clock",
        "format": "HH:mm",
        "style": { "tint": "#88C0D0", "background": "#FFFFFF18" }
      }
    ]
  }
}

Theme and item styles

Colours use #RRGGBB or #RRGGBBAA, with alpha last. An omitted bar background uses the system material. An omitted item tint uses the system primary colour; item backgrounds default to transparent. Use #00000000 to clear an inherited background.

Set these properties inside theme:

Set these properties inside theme.itemStyle or an item’s style:

Bar padding sits inside bar.height. Styling does not increase the bar’s height, and content that exceeds its bar region is clipped. Bar corners clip both the background and content. See bar settings for height and margins, and shadows for bar.shadow.

Hover colours

Set hoverTint and hoverBackground in theme.itemStyle for defaults, or in an item’s style for overrides. Hover colours apply to items with a primary action, secondary action, or popup:

{
  "schemaVersion": 1,
  "bar": {},
  "theme": {
    "itemStyle": {
      "horizontalPadding": 8,
      "verticalPadding": 4,
      "cornerRadius": 7,
      "hoverTint": "#FFFFFF",
      "hoverBackground": "#3B4261"
    }
  },
  "items": {
    "right": [
      {
        "id": "cpu",
        "type": "cpu",
        "primaryAction": { "kind": "application", "value": "com.apple.ActivityMonitor" },
        "style": { "background": "#292E42", "hoverBackground": "#414868" }
      }
    ]
  }
}

Both colours accept #RRGGBB and #RRGGBBAA. Each inherits independently from the theme when omitted or null. hoverTint overrides normal text and symbol colours, including provider state and segment tints. Native application icons retain their original colours. Without a hover tint, normal colours remain.

hoverBackground replaces the normal background during hover. Set it to #00000000 to clear the background, or to the normal background colour to keep it unchanged. Without a hover background, the item adds an 8% system-primary-colour highlight over its normal background.

The hover background covers the item’s full width and padding and uses its corner radius. Non-interactive items do not change on hover. See actions for click and context-menu behaviour.

Item widths

Use minWidth to reserve space for changing values while allowing longer content to grow:

{
  "id": "battery",
  "type": "battery",
  "style": { "minWidth": 80, "alignment": "trailing" }
}

This item stays at least 80 points wide. Choose a minimum that fits the longest expected value to avoid shifting nearby items.

Use width to keep an item at a fixed width:

{
  "id": "app",
  "type": "frontApplication",
  "style": { "width": 160, "alignment": "leading" }
}

Fixed-width labels stay on one line and truncate at the end. Other content that cannot fit, such as a large symbol or group, is clipped to the item bounds. width takes precedence over minWidth, including inherited values.

Both widths accept 0 to 4096 points and include symbols, text, and padding. alignment accepts leading, center, or trailing and defaults to center. Backgrounds and hover areas cover the reserved width. Overflow selection respects that space.

These fields also work in theme.itemStyle. Each inherits independently when omitted or null. Set minWidth to 0 to clear an inherited minimum. Setting width to 0 reserves no width; null inherits the theme’s fixed width. Without either width setting, items size to their content.

Symbol placement

Set symbolPosition on an item to place its symbol to the left or right of its text:

{
  "id": "battery",
  "type": "battery",
  "symbolPosition": "right"
}

This puts the battery state icon after the percentage. The default is left; omitting the setting or using null keeps that placement.

Placement applies to SF Symbols, custom font glyphs, provider state and result symbols, and native application icons. Existing symbol overrides and visibility settings still apply.

For providers with multiple segments, each symbol moves beside its own text while the segments keep their order. Throughput still shows download before upload when both arrows are on the right. An item-level symbol override sits beside the combined content.

Set placement directly on each item, including children inside groups and popovers. It is not a style or theme setting, and children do not inherit it. Groups, dividers, and spacers do not display symbols.

Change symbolPosition in the configuration file and let it reload. sbar set cannot change this property.

SF Symbol weight

Use symbolFontWeight in theme.itemStyle or an item’s style to set SF Symbol weight independently of text. It accepts regular, medium, semibold, or bold.

{
  "id": "clock",
  "type": "datetime",
  "symbol": "clock",
  "format": "HH:mm",
  "style": { "fontWeight": "regular", "symbolFontWeight": "bold" }
}

Item values override the theme’s symbol weight. Omitted or null values inherit the theme setting; when neither sets symbolFontWeight, symbols inherit the resolved text weight. Changing an item’s fontWeight does not override an explicit theme symbol weight.

This applies to every provider’s SF Symbols, including state and result symbols. Font glyph objects retain their custom font and are unaffected by symbolFontWeight.

Font glyph symbols

Every symbol accepts either an SF Symbol name or a glyph object. Install the font on your Mac first and use its font name:

{
  "id": "wifi",
  "type": "network",
  "network": {
    "interface": "wifi",
    "symbols": {
      "font": "Symbols Nerd Font Mono",
      "wifi": {
        "glyph": ""
      },
      "offline": "wifi.slash"
    }
  },
  "text": ""
}

Set glyph to literal text or a JSON Unicode escape. Set font to the installed font name. The optional size accepts 8 to 72 points. Without size, glyphs use the item or theme font size. Only the symbol uses the custom font; item text retains its normal font. Missing fonts or glyphs use macOS font fallback, which may display a missing-character box. You can mix SF Symbol strings with glyph objects.

An item-level glyph needs its own font:

{
  "id": "clock",
  "type": "datetime",
  "symbol": { "glyph": "T", "font": "Menlo", "size": 14 },
  "format": "HH:mm"
}

Within any provider’s symbols block, glyphs can inherit font and size from that block. Each glyph can override either value. A glyph must set a font or inherit one. SF Symbol strings ignore these font settings. Glyphs returned by commands and plugins must include their own font; they do not inherit the configured symbol font.

Battery symbols.levels accepts exactly five symbols, ordered 0%, 25%, 50%, 75%, 100%:

{
  "id": "battery",
  "type": "battery",
  "battery": {
    "symbols": {
      "font": "Symbols Nerd Font Mono",
      "levels": [
        { "glyph": "\uf244" },
        { "glyph": "\uf243" },
        { "glyph": "\uf242" },
        { "glyph": "\uf241" },
        { "glyph": "\uf240" }
      ],
      "charging": { "glyph": "\uf0e7" }
    }
  }
}

Omitted state symbols use each provider’s defaults. An item-level symbol overrides state and result symbols. A provider’s showSymbol: false hides the symbol regardless of these settings. With frontApplication.showIcon: true, the native application icon takes precedence over the item symbol.

Use sbar set to change an item-level symbol to a glyph object. This change lasts until reload or restart.

Text and provider appearance

Use the item-level text field to replace labels with provider values or conditional text. An empty template hides the label while retaining item-level symbols and provider hide rules. Use conditional symbol tags to show native symbols or application icons only in selected states. Workspace loops preserve per-entry highlighting. Throughput loops preserve direction icons when they contain {{symbol}}; an empty template hides those icons.

Provider appearance

Use each provider’s configuration block to change its state symbols, tints, and visibility.

Battery appearance

Battery items show dynamic symbols by default. Add a battery block to customise the symbols and state tints. See battery appearance for charging states and the low-battery threshold.

Volume appearance

Configure volume.symbols and volume.tints for volume levels, mute, fixed volume, and unavailable output. See volume appearance for defaults and level boundaries.

Audio device appearance

Customise audioDevice.symbols with output, input, disconnected, and unavailable keys. Glyphs inherit audioDevice.symbols.font and optional size. Tints use available, disconnected, and unavailable. Use top-level text conditions for custom state labels or text: "" for icon-only output. See audio device appearance for defaults, input selection, and missing-device visibility.

Mail appearance

Mail uses envelope.badge when the combined inbox has unread messages and envelope for zero unread or error states. An item-level symbol overrides both; symbolPosition controls its placement. Use shared styling for colours and widths. There is no dedicated mail block or option to hide the symbol or zero counts. Use text to customise its count label. See Mail for output and Automation permissions.

Network connection symbols

Network items show connection icons by default. Customise network.symbols with wifi, ethernet, cellular, other, and offline state keys. Glyphs inherit network.symbols.font and optional size. Each symbol can override these values. An item-level symbol overrides the connection icon; network.showSymbol: false hides it. Use top-level text: "" for icon-only output. See network appearance for defaults, labels, tints, and interface filtering.

VPN connection appearance

Customise vpn.symbols and vpn.tints for connecting, connected, disconnecting, disconnected, and unavailable. Glyphs inherit vpn.symbols.font and optional size. Use text: "VPN {{status}}" for an aggregate label or text: "" for icon-only output. See VPN appearance for defaults, state precedence, and visibility when disconnected or unavailable.

Bluetooth state appearance

Customise bluetooth.symbols and bluetooth.tints for on, off, connected, unauthorized, and unavailable. Glyphs inherit bluetooth.symbols.font and optional size. Use text: "Bluetooth {{status}}" for a status-only label or text: "" for icon-only output. See Bluetooth appearance for defaults, device names, and visibility when disconnected or access is denied.

CPU state appearance

CPU items show a state icon by default. Configure cpu.symbols and cpu.tints for low, medium, high, and unavailable. Glyphs inherit cpu.symbols.font and optional size. Each symbol can override these values. Thresholds use the rounded, smoothed percentage. See CPU appearance for visibility settings, defaults, and smoothing behaviour.

Memory state appearance

Memory items show a memorychip icon by default and questionmark when unavailable. Customise memory.symbols.available and memory.symbols.unavailable; glyphs inherit memory.symbols.font and optional size. Each symbol can override these values. See memory appearance for display formats and visibility settings.

Disk state appearance

Disk items show internaldrive for valid readings and questionmark when unavailable. Customise disk.symbols.available and disk.symbols.unavailable, with shared glyph font and size settings. Use disk.tints for normal, warning, critical, and unavailable states. Thresholds compare free percentage even when the item displays used percentage. See disk appearance for defaults and capacity formats.

Throughput direction symbols

Use a transfers loop with {{symbol}} to retain direction icons in a custom template.

Throughput items show separate download and upload icons by default. Customise throughput.symbols.download, upload, and unavailable, with shared glyph font and size settings. An item-level symbol replaces directional icons with one fixed icon; throughput.showSymbol: false hides it. See throughput appearance for direction visibility, units, and smoothing.

Media playback symbols

Media items show playback state icons by default. Customise media.symbols.playing, paused, stopped, and unavailable, with shared glyph font and size settings. An item-level symbol overrides state icons; media.showSymbol: false hides it. See media appearance for source selection and track visibility.

Spaces appearance

Spaces items show rectangle.3.group by default and questionmark when unavailable. Customise spaces.symbols.available and unavailable, with shared glyph font and size settings. Use spaces.tints.active and inactive for list entries and unavailable for unreadable state. The active list entry is bold. See Spaces appearance for scope, labels, and fullscreen filtering.

AeroSpace appearance

AeroSpace items show rectangle.3.group by default and questionmark when unavailable. Customise aerospace.symbols.available and unavailable, with shared glyph font and size settings. Use aerospace.tints.focused, visible, inactive, and unavailable for workspace states; focused takes precedence over visible. See AeroSpace appearance for scope, labels, and list formatting.

Yabai appearance

Yabai items show rectangle.3.group by default and questionmark when unavailable. Customise yabai.symbols.available and unavailable, with shared glyph font and size settings. Use yabai.tints.focused, visible, inactive, and unavailable for Space states; focused takes precedence over visible. See Yabai appearance for scope, list formatting, and fullscreen filtering.

Shell command appearance

Shell commands can return a JSON symbol, tint, and hidden state alongside text. Configure command.symbols and command.tints for running, success, and failure states. An item-level symbol takes precedence over state symbols, then result symbols. See shell command appearance for precedence and error policies.

Process plugin appearance

Process plugins can stream JSON symbols, tints, and visibility alongside text. Configure plugin.symbols and plugin.tints for running, success, and failure states. Item symbols override state symbols, then result symbols; each output message replaces the previous result. See process plugin appearance for precedence and error policies.