Spaces

Output #

The focused native macOS Space’s one-based position across displays, with a rectangle.3.group icon by default. Fullscreen Spaces are included. Omitting the spaces block is equivalent to spaces: {}; no window manager is required.

Configuration #

Use the item-level text template to customise or hide the label.

Set these options inside spaces.

Scope and labels #

With scope: "focused", every bar shows the same focused Space within the ordering across displays. With scope: "display", each bar uses its own display’s Space list and active Space. When macOS shares Spaces across displays, bars use the shared list.

Positions are numbered after scope and fullscreen filtering. They can change when Spaces are reordered, added, or removed. Use workspaceId to match a native Space ID instead.

Fullscreen Spaces #

With includeFullscreen: false, name and value are Fullscreen when a fullscreen Space is active, and index is empty. The fullscreen field remains true. The loop contains the remaining desktop Spaces with none highlighted. Use {{^workspaces}}{{value}}{{/workspaces}} for a fallback when no entries remain; available can still be true.

Appearance #

Symbols accept SF Symbol names or font glyph objects. Use symbolFontWeight to set SF Symbol weight independently of text.

An item-level symbol overrides both state icons. showSymbol: false hides all symbols, including this override. Tints accept #RRGGBB or #RRGGBBAA; omitted tints inherit the normal item style. Icon-only items retain an accessibility label describing the active Space or unavailable state.

To change spaces, edit the configuration file. sbar set cannot change this block.

Shared item options cover styling, symbols, actions, priority, and enabled state.

Text templates #

Use the item-level text setting to customise the workspace label. See text templates for syntax and collection rules.

Outside {{#workspaces}}...{{/workspaces}}, fields describe the current workspace selected by scope. Inside the loop, entry fields describe each workspace in order. available still describes the selected current workspace. With display scope, active can be true while focused is false when another display has focus.

This labels the workspace with index=1 as Code:

{
  "id": "spaces",
  "type": "spaces",
  "text": "{{#workspaces}}{{#index=1}}Code{{/index}}{{^index=1}}{{name}}{{/index}}{{#separator}} · {{/separator}}{{/workspaces}}{{^workspaces}}{{value}}{{/workspaces}}",
  "spaces": { "scope": "display", "includeFullscreen": false }
}

For three desktop Spaces, this displays Code · 2 · 3.

Spaces highlights the active entry. Hover tint overrides entry colours. Separators use the inactive tint, or the item colour if none is set. They are never bold. Literal text inside the loop inherits the entry styling. Templates add no spacing or per-workspace click actions.

Unavailable snapshots have no current fields, available: false, and total: 0. Use {{^workspaces}}{{value}}{{/workspaces}} as an empty-list fallback.

To show the current position and total with a default-label fallback:

{
  "id": "spaces",
  "type": "spaces",
  "text": "{{#index}}{{index}} / {{total}}{{/index}}{{^index}}{{value}}{{/index}}"
}

For the second workspace in a list of four, this displays 2 / 4. When index is missing, it keeps the default label.

Scope selection, loops, and the default label use the same snapshot. Template conditions can hide entries without changing index, total, first, or last. Separators appear only between entries that render content. An inverse workspaces section tests whether the source list is empty, not whether conditions hid every entry.

Omit text for the current workspace label, or set text: "" for an icon alone. A {{symbol}} tag controls the single item icon, including inside a loop. If the template contains the tag, the icon appears only when a branch containing it renders; showSymbol: false still hides it.

Updates #

The provider refreshes on Space switches, application activation, and display changes. It combines notification bursts into one update. If a Space transition returns incomplete data, it retries a limited number of times and keeps the previous snapshot until then.

Each refresh captures Spaces across displays. Every bar uses that snapshot to show the Spaces for its display. Manual and interval items retain that state until refreshed. See refresh policies.

Current limits #

Uses private SkyLight APIs. Shows Spaces unavailable when the requested Space or display cannot be read. Lists do not switch Spaces when clicked. Positional labels can move when the Space order changes.

Example #

{
  "id": "spaces",
  "type": "spaces",
  "text": "{{#workspaces}}{{name}}{{#separator}} · {{/separator}}{{/workspaces}}{{^workspaces}}{{value}}{{/workspaces}}",
  "spaces": {
    "includeFullscreen": false,
    "scope": "display",
    "tints": {
      "active": "#FFFFFF",
      "inactive": "#888888",
      "unavailable": "#FF6666"
    }
  }
}

This lists desktop Spaces for each bar’s display, with the active entry in bold. Lists are read-only.