CPU

Output

Aggregate busy CPU usage across all cores, from 0% to 100%, rounded to the nearest whole percent. The default item displays a cpu icon and CPU N%. Omitting the cpu block is equivalent to cpu: {}.

Configuration

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

Set these options inside cpu.

Thresholds use the rounded, smoothed percentage shown by the item. With defaults, 0 to 59% is low, 60 to 84% is medium, and 85 to 100% is high.

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

An item-level symbol overrides state symbols. showSymbol: false hides all symbols, including this override. State tints override the normal item/theme tint and accept #RRGGBB or #RRGGBBAA. Icon-only items retain an accessibility label, including when usage is unavailable.

To change cpu, 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, percentage, available. See text templates for shared fields and syntax. percentage is the item’s smoothed reading, rounded to a whole number without %. It is empty when no reading is available. available is true when a reading exists, including zero. value contains the default smoothed label, such as CPU 12%, or CPU — when unavailable.

Use available to customise the percentage label while keeping the default unavailable label:

{
  "id": "cpu",
  "type": "cpu",
  "text": "{{#available}}Usage {{percentage}}%{{/available}}{{^available}}{{value}}{{/available}}"
}

This displays Usage 12% for a 12% reading, Usage 0% for zero, and CPU — when unavailable. The state icon, tint, and native accessibility description remain in place.

Updates

The provider samples CPU usage every two seconds for all displays. Each item chooses its own smoothing window. A value of 1 disables smoothing; larger values average the most recent available samples, using fewer during warm-up. Text, thresholds, and accessibility use the same smoothed percentage. Raw provider events retain the latest unsmoothed reading.

Refresh policies capture the sample history, so manual and interval items retain their whole presentation until refreshed. Smoothing does not change the underlying sampling cadence. See refresh policies.

Unavailable readings

Startup, failed reads, unchanged CPU counters, and sampling gaps longer than ten seconds show CPU — by default and clear smoothing history. Failed reads and sampling restarts also reset the counter baseline; a fresh interval is needed before usage can be shown again. Unchanged counters mean there is no usable delta, not a measured 0% load.

Current limits

No per-core view or configurable decimal precision. Thresholds affect appearance only; they do not trigger actions.

Example

{
  "id": "cpu",
  "type": "cpu",
  "cpu": {
    "smoothingSamples": 3,
    "tints": {
      "medium": "#EBCB8B",
      "high": "#BF616A",
      "unavailable": "#888888"
    }
  },
  "text": "{{#available}}{{percentage}}%{{/available}}{{^available}}—{{/available}}"
}

This shows an icon and N%, averaging up to three recent samples and using the default thresholds. When no sample is available, it shows — with a question-mark icon. Set top-level text: "" for an icon-only item, or cpu.showSymbol: false for text-only output.