.\" Generated by scdoc 1.11.5
.\" Complete documentation for this program is not available as a GNU info page
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.nh
.ad l
.\" Begin generated content:
.TH "waybar\-battery" "5" "2026\-08\-31"
.PP
.SH NAME
.PP
waybar \- battery module
.PP
.SH DESCRIPTION
.PP
The \fBbattery\fR module displays the current capacity and state (eg.\& charging) of your battery.\&
.PP
.SH CONFIGURATION
.PP
\fBbat\fR: 
.br
typeof: string 
.br
The battery to monitor, as in /sys/class/power_supply/ instead of auto detect.\&
.PP
\fBadapter\fR: 
.br
typeof: string 
.br
The adapter to monitor, as in /sys/class/power_supply/ instead of auto detect.\&
.PP
\fBfull\-at\fR: 
.br
typeof: integer 
.br
Define the max percentage of the battery, for when you'\&ve set the battery to stop charging at a lower level to save it.\& For example, if you'\&ve set the battery to stop at 80% that will become the new 100%.\&
.PP
\fBdesign\-capacity\fR: 
.br
typeof: bool 
.br
default: false 
.br
Option to use the battery design capacity instead of its current maximal capacity.\&
.PP
\fBinterval\fR: 
.br
typeof: integer 
.br
default: 60 
.br
The interval in which the information gets polled.\&
.PP
\fBstates\fR: 
.br
typeof: object 
.br
A number of battery states which get activated on certain capacity levels.\& See \fBwaybar\-states(5)\fR.\&
.PP
\fBformat\fR: 
.br
typeof: string 
.br
default: {capacity}% 
.br
The format, how information should be displayed.\&
.PP
\fBformat\-time\fR: 
.br
typeof: string 
.br
default: {H} h {M} min 
.br
The format, how the time should be displayed.\&
.PP
\fBformat\-icons\fR: 
.br
typeof: array/object 
.br
Based on the current capacity, the corresponding icon gets selected.\& 
.br
The order is \fBlow\fR to \fBhigh\fR.\& Or by the state if it is an object.\&
.PP
\fBmax\-length\fR: 
.br
typeof: integer
.br
The maximum length in character the module should display.\&
.PP
\fBmin\-length\fR: 
.br
typeof: integer 
.br
The minimum length in characters the module should accept.\&
.PP
\fBalign\fR: 
.br
typeof: float 
.br
The alignment of the label within the module, where 0 is left\-aligned and 1 is right\-aligned.\& If the module is rotated, it will follow the flow of the text.\&
.PP
\fBjustify\fR: 
.br
typeof: string 
.br
The alignment of the text within the module'\&s label, allowing options '\&left'\&, '\&right'\&, or '\&center'\& to define the positioning.\&
.PP
\fBrotate\fR: 
.br
typeof: integer
.br
Positive value to rotate the text label (in 90 degree increments).\&
.PP
\fBon\-click\fR: 
.br
typeof: string 
.br
Command to execute when clicked on the module.\&
.PP
\fBon\-click\-middle\fR: 
.br
typeof: string 
.br
Command to execute when middle\-clicked on the module using mousewheel.\&
.PP
\fBon\-click\-right\fR: 
.br
typeof: string 
.br
Command to execute when you right\-click on the module.\&
.PP
\fBon\-update\fR: 
.br
typeof: string 
.br
Command to execute when the module is updated.\&
.PP
\fBon\-scroll\-up\fR: 
.br
typeof: string 
.br
Command to execute when scrolling up on the module.\&
.PP
\fBweighted\-average\fR: 
.br
typeof: bool 
.br
default: true 
.br
Option to combine multiple batteries with different capacities.\&
.PP
\fBon\-scroll\-down\fR: 
.br
typeof: string 
.br
Command to execute when scrolling down on the module.\&
.PP
\fBsmooth\-scrolling\-threshold\fR: 
.br
typeof: double 
.br
Threshold to be used when scrolling.\&
.PP
\fBtooltip\fR: 
.br
typeof: bool 
.br
default: true 
.br
Option to disable tooltip on hover.\&
.PP
\fBbat\-compatibility\fR: 
.br
typeof: bool 
.br
default: false 
.br
Option to enable battery compatibility if not detected.\&
.PP
\fBmenu\fR: 
.br
typeof: string 
.br
Action that popups the menu.\&
.PP
\fBmenu\-file\fR: 
.br
typeof: string 
.br
Location of the menu descriptor file.\& There need to be an element of type
.RS 4
GtkMenu with id \fBmenu\fR.\&
.PP
.RE
\fBmenu\-actions\fR: 
.br
typeof: array 
.br
The actions corresponding to the buttons of the menu.\&
.PP
\fBexpand\fR: 
.br
typeof: bool 
.br
default: false 
.br
Enables this module to consume all left over space dynamically.\&
.PP
\fBevents\fR: 
.br
typeof: object 
.br
Specifies commands to be executed on specific battery states.\& See \fBEVENTS\fR section below.\&
.PP
.SH FORMAT REPLACEMENTS
.PP
\fB{capacity}\fR: Capacity in percentage
.PP
\fB{power}\fR: Power in watts
.PP
\fB{icon}\fR: Icon, as defined in \fBformat\-icons\fR.\&
.PP
\fB{time}\fR: Estimate of time until full or empty.\& Note that this is based on the power draw at the last refresh time, not an average.\&
.PP
\fB{cycles}\fR: Amount of charge cycles the highest\-capacity battery has seen.\& \fB(Linux only)\fR
.PP
\fB{health}\fR: The percentage of the highest\-capacity battery'\&s original maximum charge it can still hold.\&
.PP
.SH TIME FORMAT
.PP
The \fBbattery\fR module allows you to define how time should be formatted via \fBformat\-time\fR.\&
.PP
The three arguments are:
\fB{H}\fR: Hours
\fB{M}\fR: Minutes
\fB{m}\fR: Zero\-padded minutes
.PP
.SH CUSTOM FORMATS
.PP
The \fBbattery\fR module allows one to define custom formats based on up to two factors.\& The best\-fitting format will be selected.\&
.PP
\fBformat\-<state>\fR: With \fBstates\fR, a custom format can be set depending on the capacity of your battery.\&
.PP
\fBformat\-<status>\fR: With the status, a custom format can be set depending on the status in /sys/class/power_supply/<bat>/status (in lowercase).\&
.PP
\fBformat\-<status>\-<state>\fR: You can also set a custom format depending on both values.\&
.PP
.SH STATES
.PP
.PD 0
.IP \(bu 4
Every entry (\fBstate\fR) consists of a \fB<name>\fR (typeof: \fBstring\fR) and a \fB<value>\fR (typeof: \fBinteger\fR).\&
.IP \(bu 4
The state can be addressed as a CSS class in the \fBstyle.\&css\fR.\& The name of the CSS class is the \fB<name>\fR of the state.\&	Each class gets activated when the current capacity is equal to or below the configured \fB<value>\fR.\&
.IP \(bu 4
Also each state can have its own \fBformat\fR.\& Those can be configured via \fBformat\-<name>\fR.\& Or if you want to differentiate a bit more even as \fBformat\-<status>\-<state>\fR.\& For more information see \fBcustom\-formats\fR.\&
.PD
.PP
.SH EVENTS
.PP
Every entry in the \fBevents\fR object consists of a \fB<event\-name>\fR (typeof: \fBstring\fR) and a \fB<command>\fR (typeof: \fBstring\fR).\& 
.br
\fB<event\-name>\fR can be in one of the following formats:
.PP
.PD 0
.IP \(bu 4
\fBon\-<status>\-<state>\fR
.IP \(bu 4
\fBon\-<status>\-<capacity>\fR
.PD
.PP
Where:
.PP
.PD 0
.IP \(bu 4
\fB<status>\fR is either \fBcharging\fR or \fBdischarging\fR,
.IP \(bu 4
\fB<state>\fR is the name of one of the states specified in the \fBstates\fR object,
.IP \(bu 4
\fB<capacity>\fR is a battery level value (between \fB0\-100\fR).\&
.PD
.PP
.PP
.SH EXAMPLES
.PP
.nf
.RS 4
"battery": {
	"bat": "BAT2",
	"interval": 60,
	"states": {
		"warning": 30,
		"critical": 15
	},
	"events": {
		"on\-discharging\-warning": "notify\-send \-u normal \&'Low Battery\&'",
		"on\-discharging\-critical": "notify\-send \-u critical \&'Very Low Battery\&'",
		"on\-charging\-100": "notify\-send \-u normal \&'Battery Full!\&'"
	},
	"format": "{capacity}% {icon}",
	"format\-icons": ["", "", "", "", ""],
	"max\-length": 25
}
.fi
.RE
.PP
.SH STYLE
.PP
.PD 0
.IP \(bu 4
\fB#battery\fR
.IP \(bu 4
\fB#battery.\&<status>\fR
.RS 4
.IP \(bu 4
\fB<status>\fR is the value of /sys/class/power_supply/<bat>/status in lowercase.\&
.RE
.IP \(bu 4
\fB#battery.\&<state>\fR
.RS 4
.IP \(bu 4
\fB<state>\fR can be defined in the \fBconfig\fR.\& For more information see \fBstates\fR.\&
.RE
.IP \(bu 4
\fB#battery.\&<status>.\&<state>\fR
.RS 4
.IP \(bu 4
Combination of both \fB<status>\fR and \fB<state>\fR.\&
.PD
.PP
.RE
The following classes are applied to the entire Waybar rather than just the
battery widget:
.PP
.PD 0
.IP \(bu 4
\fBwindow#waybar.\&battery\-<state>\fR
.RS 4
.IP \(bu 4
\fB<state>\fR can be defined in the \fBconfig\fR, as previously mentioned.\&
.PD
.PP
.RE