Output
Battery percentage with an icon for the charge level or power state. When no power source has readable capacity data, the provider shows AC power and a plug icon. This includes Macs without a battery. Omitting the battery block is equivalent to battery: {}.
Configuration
Use the item-level text template to customise or hide the label.
Set these options inside battery. Use showSymbol: false for text-only output or top-level text: "" for an icon-only item.
| Property | Default | Description |
|---|---|---|
showSymbol | true | Show the state icon, including an item-level symbol override. |
lowThreshold | 20 | Apply tints.low at or below this percentage while on battery power. Integer 0 to 100, inclusive. |
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.levels | Five system battery icons | Exactly five symbols for 0, 25, 50, 75, 100%; nearest 25% step. |
symbols.charging | battery.100percent.bolt | Charging icon. |
symbols.pluggedIn | powerplug | AC power without charging icon. |
tints.low | Normal tint | At or below threshold while on battery. |
tints.charging | Normal tint | Charging colour. |
tints.pluggedIn | Normal tint | AC power without charging colour. |
An item-level symbol overrides the battery-level, charging, and plug icons. showSymbol: false hides that override too.
Symbols accept SF Symbol names or font glyph objects. Use symbolFontWeight to set SF Symbol weight independently of text.
Shared item options cover styling, symbols, actions, priority, and enabled state.
Text templates
The item-level text setting supports id, value, symbol, percentage, charging, pluggedIn, available, status. See text templates for shared fields and syntax. Templates retain state colours and native accessibility descriptions. Templates without {{symbol}} retain the normal icon behaviour. If a template contains the tag, the icon appears only when a branch containing it renders; showSymbol: false still hides it.
status is charging, pluggedIn, onBattery, or noBattery. Use state conditions to choose a label for each state.
noBattery means no percentage reading, matching the AC power fallback. Otherwise charging takes precedence over plugged-in power, then battery power. percentage is a whole number without %, calculated using integer division and clamped to 0 through 100. available is true when a percentage reading exists, including zero.
Use available to show a custom percentage label while keeping the default fallback when no reading exists:
{
"id": "battery",
"type": "battery",
"text": "{{#available}}Battery {{percentage}}%{{/available}}{{^available}}{{value}}{{/available}}"
}
This displays Battery 75% for a 75% reading and AC power when no capacity is available. It retains the normal state icon.
Updates
The provider reads the power sources when enabled, then follows native power-source events. See refresh policies for snapshot and trigger behaviour.
Current limits
The provider uses the first power source with readable capacity data. There is no power-source selector or time-remaining estimate.
Example
{
"id": "battery",
"type": "battery",
"battery": {
"lowThreshold": 20,
"tints": {
"low": "#FF6655",
"charging": "#66CC88"
}
}
}