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 behaves the same as spaces: {}; no window manager is required.

Example

{
  "id": "spaces",
  "type": "spaces",
  "text": "{{#workspaces}}{{#index=1}}Code{{/index}}{{^index=1}}{{name}}{{/index}}{{#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. The template names the first position Code. Lists are read-only.

Configuration

Use the item-level text template to customise or hide the label. The provider options below control its data, symbols, colours, and visibility.

All fields below are inside spaces.

Scope and formats

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.

Use text to choose the presentation:

Conditions on index rename positions after scope and fullscreen filtering. Positions can change when Spaces are reordered, added, or removed. Use workspaceId to match the source Space instead.

Fullscreen Spaces

With includeFullscreen: false, value is Fullscreen when a fullscreen Space is active, and index is empty. 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.

State 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 it regardless. 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

The item-level text setting supports id, value, symbol, workspaces, separator, name, index, workspaceId, total, active, focused, visible, fullscreen, available, first, last. See workspace fields and lists for field meanings and conditions. Outside a loop, fields describe the current workspace selected by scope; inside workspaces, they describe each entry. Loops retain per-entry colour and emphasis. Separators use the inactive tint and are never bold.

Omit text for the current workspace label, or set text: "" for an icon alone. Templates do not add per-workspace click actions.

Updates

The provider refreshes on Space switches, application activation, and display changes. The provider 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.