Output
Battery percentage with an icon for the charge level or power state. A Mac without a battery shows AC power and a plug icon. Omitting the battery block behaves the same as battery: {}.
Example
{
"id": "battery",
"type": "battery",
"battery": {
"lowThreshold": 20,
"tints": {
"low": "#FF6655",
"charging": "#66CC88"
}
}
}
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 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. |
lowThreshold | 20 | 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. |
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 syntax and field meanings. percentage contains no percent sign. State symbols, colours, and accessibility descriptions remain unchanged.
status is charging, pluggedIn, onBattery, or noBattery. Use state conditions to choose a label for each state.
Updates
The provider 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. Use text to customise percentage labels.