Shared item options

Place items in items.left, items.center, or items.right in display order. Omitted sections are empty. Item snippets on provider pages belong inside one of these arrays.

Properties #

The Mail provider accepts a mail block to configure polling.

Actions #

Set primaryAction to run an action on click, or secondaryAction to add it to the context menu. Each action needs a kind and value. The kind can be command, url, or application. URL actions allow HTTP, HTTPS, and mailto. Application values are bundle IDs or paths. URL and application paths support ${NAME} and ~ expansion. Shell actions use /bin/sh -c and inherit the environment.

{
  "id": "settings",
  "type": "text",
  "primaryAction": {
    "kind": "application",
    "value": "com.apple.systempreferences"
  },
  "secondaryAction": {
    "kind": "command",
    "value": "open -a 'Activity Monitor'"
  },
  "text": "Settings"
}

Shell actions have a five-second timeout and a 64 KB combined stdout/stderr limit. They do not display command output in the item; use a command item for that. Inspect action failures with sbar query --diagnostics.

If an item has both a primary action and a popover, clicking it runs the action and opens or closes the popover. Groups render inline children, so put primary actions on the child items.

Items with either action or a popup show a hover highlight. Set hover colours to customise their text, symbols, and background.

Containers and overflow #

group items render children in a row in horizontal bars and a column in side bars. popup items show children when clicked; any item can also have a popup text string. Groups nest up to eight levels. Disabling a group disables its child providers.

A popup’s visible label defaults to its item ID. Child providers run while the container is enabled, even when its popover is closed. A container’s style applies to the container itself. Use theme.itemStyle for child defaults, a group’s childStyle for inherited overrides, and each child’s style for its own overrides.

Set symbolPosition on each child that needs it. Children do not inherit their container’s placement.

{
  "id": "system",
  "type": "popup",
  "children": [
    {
      "id": "cpu",
      "type": "cpu"
    },
    {
      "id": "memory",
      "type": "memory"
    }
  ],
  "text": "System"
}

Group spacing #

itemSpacing and childStyle require an unreleased build from main. In v0.0.1, groups use a fixed 4-point gap and children inherit the theme unless they have their own style. See release compatibility.

Set itemSpacing on a group to change the gap between its children. It accepts 0 to 96 points and defaults to 4. Nested groups use their own spacing. Theme and region itemSpacing settings control the gaps between top-level items.

Children inherit padding, width, and other styles from theme.itemStyle. Use the group’s childStyle to override those defaults for all its children. A child’s own style overrides matching fields in childStyle. Nested groups inherit these defaults and can set their own childStyle.

To keep symbols close together, remove child padding with childStyle.horizontalPadding: 0:

{
  "id": "status",
  "type": "group",
  "itemSpacing": 2,
  "childStyle": { "horizontalPadding": 0 },
  "children": [
    {
      "id": "volume",
      "type": "volume",
      "text": ""
    },
    {
      "id": "network",
      "type": "network",
      "text": ""
    },
    {
      "id": "battery",
      "type": "battery",
      "text": ""
    }
  ]
}

Use the group’s style.horizontalPadding to add space around the whole group. If the theme sets minWidth, set childStyle.minWidth to 0 to let children shrink to their content. A fixed width still takes precedence over minWidth.

Overflow #

Horizontal bars measure item widths; side bars measure item heights. Popovers open towards the middle of the display and keep their items horizontal.

Disabled items and items hidden by their provider take no layout space or inter-item spacing and do not appear in overflow. Hidden children are also excluded from groups and popovers. A group with no visible children is hidden, including an empty group or one that contains only hidden nested groups. Items hidden by a provider keep updating while enabled, so they can reappear when their state changes.

Each region moves low-priority items into an overflow popover when space runs out. Horizontal bars also allow flexible text to compress. Larger priority values remain visible longer; equal priorities hide from the end. The centre reserves one third of the bar length when populated. When a top bar crosses a notch, the centre and right sections share the usable right-hand area. Bar content stays clipped within its own region.

style.minWidth and style.width reserve horizontal space during overflow selection. Fixed-width items retain that width; their long labels truncate instead of shrinking the reserved space.

Dividers and spacers #

A divider draws a separator across the bar. A spacer adds flexible empty space along it. Both require an id and type, and neither displays a label or symbol:

{
  "schemaVersion": 1,
  "bar": {},
  "items": {
    "left": [
      {
        "id": "title",
        "type": "text",
        "text": "Work"
      },
      {
        "id": "gap",
        "type": "spacer"
      },
      {
        "id": "separator",
        "type": "divider"
      },
      {
        "id": "app",
        "type": "frontApplication"
      }
    ]
  }
}