Battery Widget Configuration

Helps you keep an eye on your battery's charge level, remaining life, health, and charging status. It comes with clean circular or linear progress bars, blinking animations while charging, and alerts based on custom battery level thresholds.

Option	Type	Default	Description
`label`	string	`{icon}`	The primary label format.
`label_alt`	string	`{percent}% \\| remaining: {time_remaining}`	The alternative label format.
`class_name`	string	`""`	Additional CSS class name for the widget.
`update_interval`	integer	`5000`	The interval in milliseconds to update the widget (0–60000).
`time_remaining_natural`	boolean	`False`	Whether to display the remaining time in a natural format.
`time_remaining_unlimited_icon`	string	`unlimited`	Which string to use to display unlimited time remaining.
`hide_unsupported`	boolean	`True`	Whether to hide the widget if the current system does not have battery info.
`charging_options`	dict	See below	Options for charging state display.
`status_thresholds`	dict	See below	Thresholds for different battery statuses.
`status_icons`	dict	See below	Icons for different battery statuses.
`keybindings`	list	`[]`	Optional hotkeys. See Keybindings.
`callbacks`	dict	See below	Callback functions for different mouse button actions.
`progress_bar`	dict	See below	Progress bar settings.

Charging Options#

The charging_options option accepts the following keys. All keys are optional, the values shown are the defaults.

charging_options:
  icon_format: "{charging_icon} {icon}"
  blink_charging_icon: true
  blink_interval: 500

Callbacks#

The callbacks option maps mouse buttons (on_left, on_middle, on_right) to actions. All keys are optional, the values shown are the defaults.

callbacks:
  on_left: "toggle_label"
  on_middle: "do_nothing"
  on_right: "do_nothing"

Available actions:

update_label - Refresh the label now.
toggle_label - Switch between label and label_alt.
do_nothing - Do nothing.
exec <command> - Run a command, for example exec cmd.exe /c start ms-settings:network.

Status Thresholds Options#

The status_thresholds option accepts the following keys. All keys are optional, the values shown are the defaults.

status_thresholds:
  critical: 10
  low: 25
  medium: 75
  high: 95
  full: 100

Status Icons Options#

The status_icons option accepts the following keys. All keys are optional, the values shown are the defaults.

status_icons:
  icon_charging: "\uf0e7"
  icon_critical: "\uf244"
  icon_low: "\uf243"
  icon_medium: "\uf242"
  icon_high: "\uf241"
  icon_full: "\uf240"

Progress Bar Options#

The progress_bar option accepts the following keys. All keys are optional, the values shown are the defaults.

progress_bar:
  enabled: false
  progress_type: "circular"
  size: 18
  thickness: 3
  radius: 0
  color: "#00C800"
  background_color: "#3C3C3C"
  position: "left"
  animation: true

Label Placeholders#

Placeholder	Description	Example Output
`{icon}`	Battery icon based on current status	`{icon}`
`{percent}`	Current battery percentage	`75`
`{time_remaining}`	Time remaining (or "unlimited"/"unknown")	`2:30:00`
`{is_charging}`	Whether battery is charging	`yes` or `no`
`{power}`	Power drain/charge rate in watts	`15.5`
`{voltage}`	Current voltage in volts	`12.45`
`{capacity}`	Current capacity in mWh	`45000`
`{full_capacity}`	Full charge capacity in mWh	`60000`
`{designed_capacity}`	Original design capacity in mWh	`62000`
`{temperature}`	Battery temperature in Celsius	`35.5`
`{cycle_count}`	Battery charge cycle count	`250`
`{health}`	Battery health percentage	`96.8`
`{chemistry}`	Battery chemistry type	`LiP`

Note

Extended battery info ({power}, {voltage}, {temperature}, etc.) requires hardware support. If not available, displays N/A.

Example Configuration#

battery:
  type: "yasb.battery.BatteryWidget"
  options:
    label: "<span>{icon}</span> {percent}%"
    label_alt: "<span>{icon}</span> {percent}% | {power}W | {time_remaining}"
    update_interval: 5000
    time_remaining_natural: False
    hide_unsupported: True
    charging_options:
      icon_format: "{charging_icon} {icon}"
      blink_charging_icon: true
      blink_interval: 500
    status_thresholds:
      critical: 10
      low: 25
      medium: 75
      high: 95
      full: 100
    status_icons:
      icon_charging: "\uf0e7"
      icon_critical: "\uf244"
      icon_low: "\uf243"
      icon_medium: "\uf242"
      icon_high: "\uf241"
      icon_full: "\uf240"

Description of Options#

label: The primary label format for the battery widget. You can use placeholders like {icon} to dynamically insert the battery icon.
label_alt: The alternative label format for the battery widget. Useful for displaying additional battery details such as {percent}% and remaining: {time_remaining}.
class_name: Additional CSS class name for the widget. This allows for custom styling.
update_interval: The interval in milliseconds to update the widget.
time_remaining_natural: A boolean indicating whether to display the remaining time in a natural format.
time_remaining_unlimited_icon: A string to display unlimited time remaining.
hide_unsupported: A boolean indicating whether to hide the widget if the current system does not have battery information.
charging_options: A dictionary specifying options for displaying the charging state. It contains:
icon_format: The format string for the charging icon. You can use placeholders like {charging_icon} and {icon}.
blink_charging_icon: A boolean indicating whether to blink the charging icon when the battery is charging. (to create a blinking effect use class blink in CSS)
blink_interval: The interval in milliseconds for the blinking effect (100–5000).
status_thresholds: A dictionary specifying the thresholds for different battery statuses. It contains:
critical: The battery percentage threshold for critical status.
low: The battery percentage threshold for low status.
medium: The battery percentage threshold for medium status.
high: The battery percentage threshold for high status.
full: The battery percentage threshold for full status.
status_icons: A dictionary specifying the icons for different battery statuses. It contains:
icon_charging: The icon for charging status.
icon_critical: The icon for critical status.
icon_low: The icon for low status.
icon_medium: The icon for medium status.
icon_high: The icon for high status.
icon_full: The icon for full status.
keybindings: A list of global hotkeys for this widget. See Keybindings.
callbacks: Mouse event callbacks. See Callbacks.
progress_bar: A dictionary containing settings for the progress bar. It includes:
enabled: Whether the progress bar is enabled.
progress_type: The type of progress bar. Options are "circular", "linear_horizontal", or "linear_vertical".
position: The position of the progress bar, either "left" or "right".
size: The length of the progress bar (or diameter if circular). Minimum is 1, maximum is 200.
thickness: The thickness of the progress bar. Minimum is 1, maximum is 100.
radius: The border radius for the linear progress bar corners. Minimum is 0, maximum is 100.
color: The color of the progress bar. Color can be a single color or a gradient. For example, color: "#57948a" or color: ["#57948a", "#ff0000"] for a gradient.
background_color: The background color of the progress bar.
animation: Whether to enable smooth change of the progress bar value.

Style#

.battery-widget {}
.battery-widget .widget-container {}
.battery-widget .widget-container .label {}
.battery-widget .widget-container .label.alt {}
.battery-widget .widget-container .icon {}
/* Status classes */
.battery-widget .widget-container .label.status-critical {}
.battery-widget .widget-container .label.status-low {}
.battery-widget .widget-container .label.status-medium {}
.battery-widget .widget-container .label.status-high {}
.battery-widget .widget-container .label.status-full {}
.battery-widget .widget-container .label.status-charging {}
.battery-widget .widget-container .icon.status-critical {}
.battery-widget .widget-container .icon.status-low {}
.battery-widget .widget-container .icon.status-medium {}
.battery-widget .widget-container .icon.status-high {}
.battery-widget .widget-container .icon.status-full {}
.battery-widget .widget-container .icon.status-charging {}
.battery-widget .widget-container .icon.status-charging.blink {}
/* Progress bar styles */
.battery-widget .progress-container {}

Style Example#

.battery-widget {
    padding: 0 8px;
}
.battery-widget .label {
    font-size: 13px;
    color: #e0e0e0;
}
.battery-widget .icon {
    font-size: 14px;
    margin-right: 6px;
}
/* Critical - red */
.battery-widget .icon.status-critical {
    color: #ff4444;
}
.battery-widget .label.status-critical {
    color: #ff6b6b;
}
/* Low - orange */
.battery-widget .icon.status-low {
    color: #ff9800;
}
.battery-widget .label.status-low {
    color: #ffb74d;
}
/* Medium - yellow */
.battery-widget .icon.status-medium {
    color: #ffc107;
}
/* High - light green */
.battery-widget .icon.status-high {
    color: #8bc34a;
}
/* Full - green */
.battery-widget .icon.status-full {
    color: #4caf50;
}
/* Charging - cyan */
.battery-widget .icon.status-charging {
    color: #00bcd4;
}
.battery-widget .label.status-charging {
    color: #4dd0e1;
}

Battery Widget Configuration#

Charging Options#

Callbacks#

Status Thresholds Options#

Status Icons Options#

Progress Bar Options#

Label Placeholders#

Example Configuration#

Description of Options#

Style#

Style Example#