waybar-battery(5)

✨ waybar-battery — the battery module, bestie edition ✨

okay so you're here because you want Waybar to tell you how much juice your laptop has left, and honestly? iconic choice. this is part of the waybar family of man pages, and it's all about the battery module. let's get into it 💅

---

💖 NAME 💖

waybar battery module — like, it shows your battery's current capacity and state (charging, etc.) because we all deserve to know when we're about to die (battery-wise, bestie, not emotionally).

---

🌸 DESCRIPTION 🌸

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

That's it. That's the whole vibe. It tells you your percent and what your battery is doing about it. 🦋

---

🎀 CONFIGURATION 🎀

okay this is the big one, the main character section, so pay attention bestie. every option goes in your Waybar config under battery.

• bat — typeof: string. the battery you wanna monitor, like as it appears in /sys/class/power_supply/. use this instead of auto detect. be specific. manifest it. ✨
• adapter — typeof: string. the adapter to monitor, as in /sys/class/power_supply/, instead of auto detect. yes you can pick your adapter too, we're not gatekeeping.
• full-at — typeof: integer. defines the max percentage of the battery — this one's for when you've set the battery to stop charging at a lower level to save its lil life. for example, if you've set your battery to stop at 80%, that 80% becomes the new 100%. it's giving "we redefined the ceiling." 👑
• design-capacity — typeof: bool, default: false. use the battery's design capacity instead of its current maximal capacity. the OG number, not the degraded one.
• interval — typeof: integer, default: 60. how often (in seconds, iykyk) the info gets polled. every 60 seconds by default. keep up bestie.
• states — typeof: object. a bunch of battery states that get activated at certain capacity levels. see waybar-states(5) for the whole tea. 🔥
• format — typeof: string, default: {capacity}%. how the info should be displayed. you literally get to choose.
• format-time — typeof: string, default: {H} h {M} min. how the time should be displayed. vibe-customizable, we love to see it.
• format-icons — typeof: array/object. based on the current capacity, the right icon gets picked. order is low to high. or, if it's an object, it goes by the state. either way, cute. 🌈
• max-length — typeof: integer. the maximum length in characters 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 inside the module. 0 is left-aligned, 1 is right-aligned. if the module is rotated, it follows the flow of the text, like it's got a mind of its own.
• justify — typeof: string. the alignment of the text inside the module's label. options are 'left', 'right', or 'center'. pick your fighter.
• rotate — typeof: integer. positive value to rotate the text label — in 90 degree increments. spin it, bestie. 🌀
• on-click — typeof: string. command to run when you click on the module.
• on-click-middle — typeof: string. command to run when you middle-click (the mousewheel click, you know the one) on the module.
• on-click-right — typeof: string. command to run when you right-click the module.
• on-update — typeof: string. command to run when the module is updated.
• on-scroll-up — typeof: string. command to run when you scroll up on the module.
• weighted-average — typeof: bool, default: true. combines multiple batteries with different capacities. because math deserves flair too.
• on-scroll-down — typeof: string. command to run when you scroll down on the module.
• smooth-scrolling-threshold — typeof: double. the threshold used when scrolling. yes, it's a double.
• tooltip — typeof: bool, default: true. option to disable the tooltip on hover. keep it on unless you hate hover tea.
• bat-compatibility — typeof: bool, default: false. enables battery compatibility if it's not being detected. the "just in case" option. 🫶
• menu — typeof: string. the action that pops up the menu.
• menu-file — typeof: string. where the menu descriptor file lives. there needs to be an element of type GtkMenu with id menu. periodt.
• menu-actions — typeof: array. the actions that correspond to the buttons of the menu.
• expand — typeof: bool, default: false. lets this module consume all left over space dynamically. needy in a cute way.
• events — typeof: object. specifies commands to run on specific battery states. see the EVENTS section below for details.

---

💫 FORMAT REPLACEMENTS 💫

these are the lil curlies you drop into your format string, and each one brings different ~energy~:

• {capacity} — capacity in percentage.
• {power} — power in watts.
• {icon} — the icon, as defined in format-icons. 🎀
• {time} — estimate of time until full or empty. ok important: this is based on the power draw at the last refresh time, not an average. so don't come for it if it's a little off, bestie.
• {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. the realness of your battery's aging. 😭

---

⏰ TIME FORMAT ⏰

the battery module lets you define how time gets formatted via format-time.

the three arguments are:

• {H} — hours
• {M} — minutes
• {m} — zero-padded minutes

---

🌟 CUSTOM FORMATS 🌟

you can define custom formats based on up to two factors, and the best-fitting format gets selected. it's giving smart. it's giving adaptive. we're obsessed.

• format-<state> — with states, you can set a custom format depending on the capacity of your battery.
• format-<status> — with the status, you can set a custom format depending on the status in /sys/class/power_supply/<bat>/status (in lowercase).
• format-<status>-<state> — and you can set a custom format depending on both values. maximum customization unlocked. 🔓

---

💅 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>. so like, when you dip below, it knows.
• Also, each state can have its own format. those can be configured via format-<name>. or, if you wanna differentiate a bit more (we love a detail queen), even as format-<status>-<state>. more info in 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 🌈

here's a real one, enjoy the tea:

"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. more info in states.
• #battery.<status>.<state>
  • Combination of both <status> and <state>. it's giving layers, it's giving dimension.

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.

---

and that's the whole page, bestie — you're officially a battery config expert. this was from the File Formats Manual, dated 2026-02-08, and honestly? slay. go forth and configure your battery module. you're the main character now. 💖✨🦋🍓

---