Yabai

Output

The focused Space’s Yabai label and a rectangle.3.group icon. If the label is missing or blank, the item shows the Mission Control index. Omitting the yabai block behaves the same as yabai: {}.

Example

{
  "id": "yabai",
  "type": "yabai",
  "text": "{{#workspaces}}{{name}}{{#separator}} · {{/separator}}{{/workspaces}}{{^workspaces}}{{value}}{{/workspaces}}",
  "yabai": {
    "includeFullscreen": false,
    "scope": "display",
    "tints": {
      "focused": "#FFFFFF",
      "visible": "#88CCFF",
      "inactive": "#888888"
    }
  }
}

This lists desktop Spaces on each bar’s display, with the focused Space in bold. 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 yabai.

Scope, labels, and fullscreen Spaces

With scope: "focused", the default label shows the focused Space on every bar, and workspaces includes Spaces across displays. With scope: "display", the default label shows that display’s visible Space even when another display has focus; lists contain only its Spaces. Display indexes are mapped using Yabai’s display UUIDs, so custom Yabai display ordering is supported.

Labels come from Yabai. Blank or missing labels fall back to Mission Control indexes, and lists follow index order. Use template conditions on name, index, or workspaceId to customise the display text. Indexes may change when Spaces are added, removed, or reordered.

With includeFullscreen: false, lists omit native fullscreen Spaces without renumbering the remaining indexes. An active fullscreen Space has value: Fullscreen and retains its native index and name. Lists retain the other Spaces without highlighting the excluded Space. Use {{^workspaces}}{{value}}{{/workspaces}} for an empty-list fallback; 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 workspace or unavailable-state information in their accessibility label.

To change yabai, 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 polls every two seconds, independently of item refresh policies. Each CLI invocation has a two-second timeout. A snapshot queries displays, then Spaces, then displays again to verify the mapping. Incomplete snapshots receive up to three attempts while retaining the previous value. Polling waits for any running refresh to finish.

Fresh queries on triggers

Manual and event triggers request fresh queries before capturing the completed result. Refresh bursts coalesce, and cancelled queries cannot publish stale results. Interval refresh captures the latest polled snapshot.

{
  "id": "yabai",
  "type": "yabai",
  "refresh": { "mode": "manual" }
}

sbar trigger yabai

Existing Yabai signals can invoke this command for an item with manual or event refresh configured. Replace yabai with the item’s ID, and add --socket <path> when targeting a custom bar socket. The bar does not install signals or change Yabai configuration. See refresh policies.

Current limits

Requires Yabai in PATH or a standard Homebrew bin directory. Missing installations display Yabai not installed; failed, malformed, or inconsistent reads display Yabai unavailable after retries. Standard output is parsed separately from diagnostics.

No executable-path override or built-in Space switching controls. Lists and labels reflect Yabai’s reported state.