Disk

Output

Capacity of a selected volume, defaulting to the home volume. The default item displays an internaldrive icon and text such as 120 GB free. Omitting the disk block behaves the same as disk: {}.

Example

{
  "id": "external",
  "type": "disk",
  "disk": {
    "path": "/Volumes/External",
    "warningThreshold": 20,
    "criticalThreshold": 10,
    "tints": {
      "warning": "#EBCB8B",
      "critical": "#BF616A",
      "unavailable": "#888888"
    }
  },
  "text": "{{#available}}{{used}} / {{total}}{{/available}}{{^available}}—{{/available}}"
}

Replace the path with an existing file or directory on the volume you want to monitor. This shows an icon and used/total capacity. Set top-level text: "" for an icon-only item, or showSymbol: false for text-only output.

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 disk.

Display formats

Bytes use macOS file-size formatting. Choose fields in top-level text. The item-level format remains for date and time items.

State appearance

Thresholds compare the unrounded free percentage, while {{percentage}}% displays the rounded used percentage. Critical takes precedence over warning. State tints override the normal item/theme tint and accept #RRGGBB or #RRGGBBAA; omitted colours use the normal tint.

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. Icon-only items retain the path, free/total capacity, and used percentage in their accessibility label, or identify the path as unavailable.

To change disk, 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, used, free, total, percentage, freeBytes, totalBytes, available. See text templates for syntax and field meanings. Fields follow the selected path. percentage measures used space, regardless of the default display format.

Updates

The provider samples disk capacity every two seconds. Paths on the same volume share one capacity read per sampling pass, across items and displays. Refresh policies capture each item’s full capacity state; manual and interval items hold their snapshot until refreshed. Changing an item’s path immediately clears its old snapshot. See refresh policies.

Disk value events use each item ID, with free-space text regardless of display mode. Unavailable values use Disk —.

Missing or unmounted volumes

Missing paths, failed reads, and invalid capacities display — unavailable with a questionmark icon by default. A valid sample restores the reading.

The provider checks the mount before and after reading. Once a path has produced a valid reading, a different mount point is treated as unavailable so an unmounted drive does not silently become a reading for its parent disk. Leftover directories under /Volumes are rejected unless they are on that mounted volume.

Current limits

The provider tracks the volume at a path, not a persistent physical-drive identity. Free and total capacity come from the filesystem’s systemFreeSize and systemSize; used is total minus free. There is no estimate of reclaimable storage or configurable units. Thresholds control colours, not actions.