Throughput

Output

Download and upload rates, with directional icons and automatically scaled units, such as 42 KiB/s and 8 KiB/s. By default, the provider combines valid rates from all non-loopback interfaces. Omitting the throughput block behaves the same as throughput: {}.

Example

{
  "id": "throughput",
  "type": "throughput",
  "text": "{{#transfers}}{{symbol}}{{value}}{{#separator}} · {{/separator}}{{/transfers}}{{^transfers}}{{symbol}}{{value}}{{/transfers}}",
  "throughput": {
    "interfaces": ["en0"],
    "unit": "bytes",
    "smoothingSamples": 3
  }
}

Replace en0 with an interface name on your Mac, or omit interfaces to combine all non-loopback interfaces. This averages up to three recent rates per interface before combining them.

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

Units and visibility

Values round to at most one decimal place, retaining small rates such as 0.5 B/s. Each direction scales independently. The number, download.value, and upload.value template fields omit suffixes while retaining automatic scaling.

Use text to select directions, numbers, units, or icons; see the examples below. showSymbol: false hides all icons. Accessibility retains both direction names, rates, and units whenever a reading is available, even when the template hides them.

An empty text hides both text and directional icons. An item-level symbol override or unavailable icon still follows showSymbol. For directional icons alone, use a transfers loop containing {{symbol}}.

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

An item-level symbol replaces the directional symbols with one fixed icon and also overrides the unavailable icon. showSymbol: false hides it regardless.

Set the item’s symbolPosition to right to put each arrow after its own rate. Download still precedes upload. With an item-level symbol override, the single icon appears after the combined content. Placement defaults to left.

To change throughput, 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, download, upload, download.value, download.unit, upload.value, upload.unit, available, transfers, direction, number, unit, separator, first, last, index, total. See text templates for syntax. Rates follow interface selection, units, and smoothing.

Entry-only fields are empty outside the loop. {{^transfers}}{{symbol}}{{value}}{{/transfers}} supplies the unavailable fallback. Explicit templates add no spacing between runs; the default presentation uses four points between directions.

A symbol tag inside a false condition suppresses that icon. Outside the loop, {{symbol}} requests the item-level override or unavailable icon; it does not select a direction. If a template contains any symbol tag, an aggregate icon appears only when a symbol tag renders. Include {{symbol}} in the inverse transfers section to retain the unavailable icon.

The symbol tag follows symbolPosition and configured direction symbols, including glyph overrides. Repeated tags in the same run request one icon. An item-level symbol replaces the direction icons, and showSymbol: false hides all icons. Scalar rate templates do not request direction icons.

For download alone:

{
  "id": "download",
  "type": "throughput",
  "text": "{{#transfers}}{{#direction=download}}{{symbol}}{{value}}{{/direction}}{{/transfers}}{{^transfers}}{{symbol}}{{value}}{{/transfers}}"
}

For scaled numbers without units, retain the icons and replace value with number:

{
  "id": "throughput",
  "type": "throughput",
  "text": "{{#transfers}}{{symbol}}{{number}}{{#separator}} · {{/separator}}{{/transfers}}{{^transfers}}{{symbol}}{{value}}{{/transfers}}"
}

For directional icons alone:

{
  "id": "throughput",
  "type": "throughput",
  "text": "{{#transfers}}{{symbol}}{{#separator}} {{/separator}}{{/transfers}}"
}

Updates

The provider samples network counters every two seconds for all displays. It calculates download and upload deltas for each interface, then combines them. Each item can choose its own interfaces and smoothing window. A window of 1 disables smoothing; larger windows use fewer samples during warm-up.

Refresh policies capture the full per-interface history, so manual and interval items retain their presentation until refreshed. Provider events retain unsmoothed all-interface rates in bytes. See refresh policies.

Interface availability

With explicit interfaces, every selected interface must have a valid rate. A missing, newly appeared, or reset interface makes the item unavailable. Without a filter, only interfaces with valid deltas contribute; new or reset interfaces join after a fresh interval. If none have valid deltas, the item is unavailable. Loopback interfaces are excluded even when explicitly named.

Startup, failed reads, sampling restarts, and gaps longer than ten seconds clear baselines and history. The default presentation is — with a questionmark icon until a fresh interval is available; accessibility reports Network throughput unavailable.

Timing uses a monotonic clock. Counter decreases, including resets or wraparound, and interface identity changes reset only that interface’s history without producing a traffic spike. Unchanged counters are a valid zero rate. Removed interfaces are discarded immediately.

Current limits

Interface names depend on the machine and do not imply Wi-Fi or Ethernet. The unfiltered total includes tunnels, which can add traffic from the same underlying transfer. No dedicated state tints or fixed-unit scale.