Output
Connected device names and status, such as Keyboard connected, Mouse connected, sorted by name, with a state-dependent icon. With no connected devices, the item shows Bluetooth on or Bluetooth off. Omitting the bluetooth block behaves the same as bluetooth: {}.
Denied or restricted access shows Bluetooth access denied. Missing hardware, read failures, or a resetting controller show Bluetooth unavailable. Device names are omitted when Bluetooth is off or inaccessible. Missing or blank names fall back to Unnamed device.
Example
{
"id": "bluetooth",
"type": "bluetooth",
"bluetooth": {
"hideWhenDisconnected": true,
"tints": {
"connected": "#8AADF4",
"unauthorized": "#ED8796"
}
}
}
This hides the item when Bluetooth is off or on with no connected devices. Connected, access-denied, and unavailable states remain visible.
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 bluetooth.
| Property | Default | Description |
|---|---|---|
showSymbol | true | Show the state icon; false hides even an item-level symbol override. |
hideWhenDisconnected | false | Hide the on and off states. Access-denied and unavailable states remain visible. |
symbols.font | - | Shared installed font name for glyph symbols; each glyph can override it. |
symbols.size | Resolved item/theme font size | Shared glyph size, 8 to 72 points; each glyph can override it. |
symbols state keys | Icons below | Override symbols for the five states. |
tints state keys | Normal tint | State colours for the same five states; accept #RRGGBB or #RRGGBBAA. |
Power, connection, and access states
symbols and tints accept these state keys:
| State key | Default symbol | Default label |
|---|---|---|
on | antenna.radiowaves.left.and.right | on |
off | antenna.radiowaves.left.and.right.slash | off |
connected | antenna.radiowaves.left.and.right | connected |
unauthorized | exclamationmark.triangle | access denied |
unavailable | exclamationmark.triangle | unavailable |
The on state means Bluetooth is powered on with no connected devices reported by the provider. With at least one connected device, the state is connected. Denied or restricted access takes precedence over the power state.
Use a devices loop to customise each connected device label. Use text: "Bluetooth {{status}}" for an aggregate label or text: "" for an icon alone. Accessibility retains the native names and statuses.
Symbols and colours
Symbols accept SF Symbol names or font glyph objects. Use symbolFontWeight to set SF Symbol weight independently of text.
An item-level symbol overrides the state icon; showSymbol: false hides it regardless. Omitted state symbols use the built-in defaults. State tints override the normal item/theme tint.
To change bluetooth, edit the configuration file. sbar set cannot change this block.
Bluetooth access
Monitoring starts only when a Bluetooth item is active. macOS may request Bluetooth access at that point. If access is denied, allow it in System Settings > Privacy & Security > Bluetooth and restart sbar.
The executable embeds the required usage description. Custom app bundles must also include NSBluetoothAlwaysUsageDescription in their Info.plist. A missing or blank usage description prevents monitoring from starting and leaves the provider unavailable.
Shared item options cover styling, symbols, actions, priority, and enabled state.
Text templates
The item-level text setting supports id, value, symbol, status, names, count, connected, devices, name, deviceId, index, total, first, last, separator. See service and device loops for field meanings and examples. names contains connected device names, sorted and comma-separated; count is their count. The devices loop contains connected devices only and is empty when Bluetooth is off, access is denied, or the provider is unavailable.
Inside the loop, value, status, and connected describe that entry; outside, they describe the aggregate state. Entry-only fields are empty outside the loop. Loops retain the aggregate symbol, tint, and hide rules.
Updates
Items and displays share one native event monitor. Core Bluetooth supplies power and access state. IOBluetooth supplies connected device names and connection notifications. Unavailable reads retry every two seconds.
The provider waits for the initial permission and power state before capturing refresh snapshots. Event items follow device and power changes. Interval and manual items hold their snapshot until refreshed or triggered. Snapshots retain device names, status, text, icon, tint, and visibility together. Triggers capture the latest shared state. See refresh policies.
Current limits
Device coverage comes from IOBluetooth’s paired-device list and new connections observed while the provider is running. Only connected devices are listed. Devices exposed only through Bluetooth Low Energy services may be absent.
The provider does not scan, pair, connect, disconnect, or change Bluetooth power. There is no device filter, and device battery levels are not included.