battery

Shows battery charge level and state via UPower. Hides itself when the selected battery is missing or not present, or with auto when the machine has neither a system battery nor a peripheral reporting a charge.

Setting	Type	Default	Description
display_mode	string	"glyph"	"none" hides the icon, "glyph" shows a glyph icon, and "graphic" draws a rectangular battery shape with an animated fill level.
show_label	bool	true	In glyph mode: show the label next to the glyph. In graphic mode: overlay it on the battery body.
label_content	string	"percent"	Label value: "percent", "time" remaining, or power-draw "rate". Available on horizontal bars when labels are enabled.
glyph_position	string	"before"	In glyph mode: place the glyph "before" or "after" the label. See Peek
peek	bool	false	In glyph mode: show only the glyph and reveal the label on hover. See Peek
peek_delay_ms	int	100	Hover time before the label reveals, from 0 to 2000 ms
hide_when_plugged	bool	false	Hide the widget while connected to AC power.
hide_when_full	bool	false	Hide the widget when fully charged.
device	string	"auto"	UPower device selector. auto monitors the system power-supply battery, or the lowest-charged peripheral when there is none; explicit selectors can target any present battery-capable UPower device.
warning_color	color	"error"	Color applied when charge is at or below the matching global/per-device [battery] warning threshold. Ignored while charging.

In graphic mode, the label is centered inside the battery body in a small font. Percentages show only the number, without a % suffix. On horizontal bars the body keeps the same size with or without a label; longer labels such as 100, time, or rate shrink their font to fit. On vertical bars the label always shows the percentage, the body is sized for two digits so it keeps one width from 1 to 99, and the label is hidden at 100%. Rate labels round to whole watts with no space before W, for example 44W; positive rates below one watt show <1W. Time labels of an hour or more use a clock style such as 2:54; shorter times show minutes, such as 53m. Tooltips and non-graphic modes keep the full forms, such as 44.3 W and 2h 54m.

The body uses the widget foreground color, or warning_color at low charge, like the battery without a label: the fill is that color, and the empty track mixes it toward the surface color role. The label uses the surface color role, so it reads on both sides of the fill boundary. Charging and plugged-in state icons remain outside the body. Theme changes update the colors immediately.

device = "auto" prefers the system battery whenever one is present, so laptops never switch to a gamepad, mouse, or headset. On desktops without a system battery, it follows whichever peripheral has the lowest charge, like the rest of the shell, and the warning color uses the global [battery] threshold. Use an explicit selector to pin the widget to one device.

Selectors can be a full UPower object path, a native path/name, a stable suffix such as BAT0, or available device metadata such as model, serial, or vendor.

# System battery, or the lowest-charged peripheral on desktops
[widget.battery]
type = "battery"
device = "auto"

# Graphical battery with percentage overlay
[widget.battery]
type = "battery"
display_mode = "graphic"

# Graphical battery without percentage text
[widget.battery]
type = "battery"
display_mode = "graphic"
show_label = false

# Internal battery by native name/suffix
[widget.internal_battery]
type = "battery"
device = "BAT0"

# Second battery by full UPower object path
[widget.second_battery]
type = "battery"
device = "/org/freedesktop/UPower/devices/battery_BAT1"

# Explicit peripheral battery
[widget.gamepad_battery]
type = "battery"
device = "/org/freedesktop/UPower/devices/gaming_input_hid_001"