---
name: "waybar-battery"
section: "5"
platform: "linux"
package: "waybar"
version: "0.15.0-3"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/waybar-battery"
---

# waybar-battery(5)

battery module

## NAME

waybar - battery module

## DESCRIPTION

The **battery** module displays the current capacity and state (eg. charging) of your battery.

## CONFIGURATION

**bat**: \
 typeof: string \
 The battery to monitor, as in /sys/class/power\_supply/ instead of auto detect.

**adapter**: \
 typeof: string \
 The adapter to monitor, as in /sys/class/power\_supply/ instead of auto detect.

**full-at**: \
 typeof: integer \
 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%.

**design-capacity**: \
 typeof: bool \
 default: false \
 Option to use the battery design capacity instead of its current maximal capacity.

**interval**: \
 typeof: integer \
 default: 60 \
 The interval in which the information gets polled.

**states**: \
 typeof: object \
 A number of battery states which get activated on certain capacity levels. See **[waybar-states(5)](/waybar-states/5.md)**.

**format**: \
 typeof: string \
 default: {capacity}% \
 The format, how information should be displayed.

**format-time**: \
 typeof: string \
 default: {H} h {M} min \
 The format, how the time should be displayed.

**format-icons**: \
 typeof: array/object \
 Based on the current capacity, the corresponding icon gets selected. \
 The order is **low** to **high**. Or by the state if it is an object.

**max-length**: \
 typeof: integer\
 The maximum length in character the module should display.

**min-length**: \
 typeof: integer \
 The minimum length in characters the module should accept.

**align**: \
 typeof: float \
 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.

**justify**: \
 typeof: string \
 The alignment of the text within the module's label, allowing options 'left', 'right', or 'center' to define the positioning.

**rotate**: \
 typeof: integer\
 Positive value to rotate the text label (in 90 degree increments).

**on-click**: \
 typeof: string \
 Command to execute when clicked on the module.

**on-click-middle**: \
 typeof: string \
 Command to execute when middle-clicked on the module using mousewheel.

**on-click-right**: \
 typeof: string \
 Command to execute when you right-click on the module.

**on-update**: \
 typeof: string \
 Command to execute when the module is updated.

**on-scroll-up**: \
 typeof: string \
 Command to execute when scrolling up on the module.

**weighted-average**: \
 typeof: bool \
 default: true \
 Option to combine multiple batteries with different capacities.

**on-scroll-down**: \
 typeof: string \
 Command to execute when scrolling down on the module.

**smooth-scrolling-threshold**: \
 typeof: double \
 Threshold to be used when scrolling.

**tooltip**: \
 typeof: bool \
 default: true \
 Option to disable tooltip on hover.

**bat-compatibility**: \
 typeof: bool \
 default: false \
 Option to enable battery compatibility if not detected.

**menu**: \
 typeof: string \
 Action that popups the menu.

**menu-file**: \
 typeof: string \
 Location of the menu descriptor file. There need to be an element of type

GtkMenu with id **menu**.

**menu-actions**: \
 typeof: array \
 The actions corresponding to the buttons of the menu.

**expand**: \
 typeof: bool \
 default: false \
 Enables this module to consume all left over space dynamically.

**events**: \
 typeof: object \
 Specifies commands to be executed on specific battery states. See **EVENTS** section below.

## FORMAT REPLACEMENTS

**{capacity}**: Capacity in percentage

**{power}**: Power in watts

**{icon}**: Icon, as defined in **format-icons**.

**{time}**: Estimate of time until full or empty. Note that this is based on the power draw at the last refresh time, not an average.

**{cycles}**: Amount of charge cycles the highest-capacity battery has seen. **(Linux only)**

**{health}**: The percentage of the highest-capacity battery's original maximum charge it can still hold.

## TIME FORMAT

The **battery** module allows you to define how time should be formatted via **format-time**.

The three arguments are: **{H}**: Hours **{M}**: Minutes **{m}**: Zero-padded minutes

## CUSTOM FORMATS

The **battery** module allows one to define custom formats based on up to two factors. The best-fitting format will be selected.

**format-\<state\>**: With **states**, a custom format can be set depending on the capacity of your battery.

**format-\<status\>**: With the status, a custom format can be set depending on the status in /sys/class/power\_supply/\<bat\>/status (in lowercase).

**format-\<status\>-\<state\>**: You can also set a custom format depending on both values.

## STATES

- •

  Every entry (**state**) consists of a **\<name\>** (typeof: **string**) and a **\<value\>** (typeof: **integer**).

- •

  The state can be addressed as a CSS class in the **style.css**. The name of the CSS class is the **\<name\>** of the state.	Each class gets activated when the current capacity is equal to or below the configured **\<value\>**.

- •

  Also each state can have its own **format**. Those can be configured via **format-\<name\>**. Or if you want to differentiate a bit more even as **format-\<status\>-\<state\>**. For more information see **custom-formats**.

## EVENTS

Every entry in the **events** object consists of a **\<event-name\>** (typeof: **string**) and a **\<command\>** (typeof: **string**). \
 **\<event-name\>** can be in one of the following formats:

- •

  **on-\<status\>-\<state\>**

- •

  **on-\<status\>-\<capacity\>**

Where:

- •

  **\<status\>** is either **charging** or **discharging**,

- •

  **\<state\>** is the name of one of the states specified in the **states** object,

- •

  **\<capacity\>** is a battery level value (between **0-100**).

## EXAMPLES

```
"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
}
```

## STYLE

- •

  **#battery**

- •

  **#battery.\<status\>**

  - •

    **\<status\>** is the value of /sys/class/power\_supply/\<bat\>/status in lowercase.

- •

  **#battery.\<state\>**

  - •

    **\<state\>** can be defined in the **config**. For more information see **states**.

- •

  **#battery.\<status\>.\<state\>**

  - •

    Combination of both **\<status\>** and **\<state\>**.

  The following classes are applied to the entire Waybar rather than just the battery widget:

- •

  **window#waybar.battery-\<state\>**

  - •

    **\<state\>** can be defined in the **config**, as previously mentioned.