File: README.md Copy Chapter

YASB Reborn

[Installation](https://github.com/amnweb/yasb/wiki/Installation) · [Documentation](https://github.com/amnweb/yasb/wiki) · [Themes](https://github.com/amnweb/yasb-themes) · [Discussions](https://github.com/amnweb/yasb/discussions) · [Discord](https://discord.gg/qkeunvBFgX)

📋 Installation Copy Chapter

For detailed installation instructions and system requirements, visit the installation docs.
But to get started quickly, choose one of the installation methods below:

Download .msi from GitHub

Go to the YASB GitHub releases, click Assets to reveal the downloads, and choose the installer that matches your architecture and install scope. For most devices, that's the x64 per-user installer.

WinGet

Download YASB from WinGet. Updating YASB via winget will respect the current YASB installation scope. To install YASB, run the following command from the command line / PowerShell:

User scope installer [default]

winget install AmN.yasb

Machine-wide scope installer

winget install --scope machine AmN.yasb

Scoop

Download YASB from Scoop. Updating YASB via Scoop will respect the current YASB installation scope. To install YASB using Scoop, run the following command from the command line / PowerShell:

Install YASB using Scoop

scoop bucket add extras
scoop install extras/yasb

Chocolatey

Download YASB from Chocolatey. Updating YASB via Chocolatey will respect the current YASB installation scope. To install YASB using Chocolatey, run the following command from the command line / PowerShell:

Install YASB using Chocolatey

choco install yasb

💻 Demo Copy Chapter

🛠️ List of currently available widgets in YASB. Copy Chapter

🤝 Contributors Copy Chapter

Thanks to our amazing contributors!

🔑 Code Signing Policy Copy Chapter

Free code signing provided by SignPath.io, certificate by SignPath Foundation

File: docs/widgets/(Widget)-Active-Windows-Title.md Copy Chapter

Active Window Widget Options

Shows the title of the window you are currently using right in your status bar. You can format the text however you like, switch between different label styles, automatically hide titles for specific apps, rewrite text patterns using rules, and even display the app's icon.

Example Configuration Copy Chapter

active_window:
  type: "yasb.active_window.ActiveWindowWidget"
  options:
    label: "{win[title]}"
    label_alt: "[class_name='{win[class_name]}' exe='{win[process][name]}' hwnd={win[hwnd]}]"
    label_no_window: ""
    label_icon: true
    label_icon_size: 16
    max_length: 56
    max_length_ellipsis: "..."
    monitor_exclusive: true

Description of Options Copy Chapter

• label: The format string for the active window title. You can use placeholders to dynamically insert window information. See Label Format Placeholders below.
• label_alt: The alternative format string for the active window. Useful for displaying additional window details. Supports the same placeholders as label.
• class_name: Additional CSS class name for the widget. This allows for custom styling.
• label_no_window: The text to display when no window is active. If not specified, it defaults to an empty string.
• label_icon: A boolean indicating whether to display the window icon.
• label_icon_size: The size of the window icon in pixels. Must be between 12px and 24px.
• max_length: The maximum number of characters to display for the window title. If the title exceeds this length, it will be truncated.
• max_length_ellipsis: The string to append to truncated window titles.
• monitor_exclusive: A boolean indicating whether the widget should be exclusive to a single monitor.
• ignore_window: A dictionary specifying which windows to ignore. It contains three lists: classes, processes, and titles.
• callbacks: A dictionary specifying the callbacks for mouse events. The keys are on_left, on_middle, and on_right, and the values are the names of the callback functions.
• rewrite: A dictionary containing rewrite options for the widget. Rewrite rules are applied to title, process.name, and app_name. See Rewrite Options below.

Label Format Placeholders Copy Chapter

You can use the following placeholders in label and label_alt:

Label Examples Copy Section

# Show just the window title
label: "{win[title]}"

# Show friendly app name
label: "{win[app_name]}"

# Show app name followed by window title
label: "{win[app_name]} - {win[title]}"

# Show process name and title
label: "{win[process][name]}: {win[title]}"

# Show detailed info on alt label
label_alt: "[{win[app_name]}] class='{win[class_name]}' exe='{win[process][name]}' pid={win[process][pid]}"

Rewrite Options Copy Chapter

The rewrite option allows you to supply a list of search-and-replace rules to be applied, in order, to the window title. Each rule is a dict with the following schema:

Example Copy Section

active_window:
  type: "yasb.active_window.ActiveWindowWidget"
  options:
    label: "{win[title]}"
    # ...
    rewrite:
      # Strip trailing “.exe” (case-insensitive) and lowercase:
      - pattern: "^(.+?)\\.exe$"
        replacement: "\\1"
        case: lower

      # Uppercase the literal word “Studio” anywhere in the title:
      - pattern: "\\bStudio\\b"
        replacement: "STUDIO"

      # Replace any title like “...YASB Reborn - Foo” with “🌎 Foo”
      - pattern: "(.*)YASB Reborn -(.*)$"
        replacement: "🌎 \\2"

Example Style Copy Chapter

.active-window-widget {}
.active-window-widget.your_class {} /* If you are using class_name option */
.active-window-widget .widget-container {}
.active-window-widget .widget-container .label {}
.active-window-widget .widget-container .label.alt {}
.active-window-widget .widget-container .icon {}

File: docs/widgets/(Widget)-Applications.md Copy Chapter

Applications Widget Options

A simple launcher that puts shortcut buttons for your favorite apps and tools right on the bar. You can launch any command or program with a click, set up custom icons (using text symbols or local images), and customize the hover tooltips.

Example Configuration Copy Chapter

apps:
  type: "yasb.applications.ApplicationsWidget"
  options:
    label: "{data}"
    app_list:
      - {icon: "\uf0a2", launch: "notification_center", name: "Notification Center"} # launch notification center
      - {icon: "\ueb51", launch: "quick_settings"} # launch quick settings
      - {icon: "\uf422", launch: "search"} # launch search
      - {icon: "\uf489", launch: "wt", name: "Windows Terminal"} # launch terminal
      - {icon: "C:\\Users\\marko\\icons\\vscode.png", launch: "C:\\Users\\Username\\AppData\\Local\\Programs\\Microsoft VS Code\\Code.exe"} # open vscode
      - {icon: "\udb81\udc4d",launch: "\"C:\\Program Files\\Mozilla Firefox\\firefox.exe\" -new-tab www.reddit.com"} # open reddit in new tab in firefox
      - {icon: "\udb81\udc4d",launch: "\"C:\\Program Files\\Mozilla Firefox\\firefox.exe\" -new-window www.reddit.com"} # open reddit in new window in firefox
      - {icon: "\udb81\udc4d",launch: "\"C:\\Program Files\\Mozilla Firefox\\firefox.exe\" -private-window www.reddit.com"} # open reddit in private window in firefox

Description of Options Copy Chapter

• label: The label for the applications widget.
• class_name: The CSS class name for styling the widget. Optional.
• image_icon_size: The size of the icon in pixels if the icon is an image.
• app_list: A list of applications to display in the widget. Each application can be specified as a string (the command to launch) or as a dictionary with the following keys:
  • icon: The icon for the application. This can be a Unicode character (e.g., \uf0a2), an image path (e.g., C:\\path\\to\\icon.png), or an icon name that can be resolved by the system.
  • launch: The command to launch the application. This can include arguments and should be properly quoted if necessary.
  • name: (Optional) The name of the application to display as a tooltip when hovering over the icon.
• tooltip: A boolean to enable or disable tooltips for application names.

[!NOTE]
If you use image as icon, you need to provide the full path to the image. Recommended to use small images.

Example Style Copy Chapter

.apps-widget {}
.apps-widget .widget-container {}
.apps-widget .widget-container .label { /*icons*/ }

File: docs/widgets/(Widget)-Battery.md Copy Chapter

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.

Label Placeholders Copy Chapter

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

Example Configuration Copy Chapter

battery:
  type: "yasb.battery.BatteryWidget"
  options:
    label: "{icon} {percent}%"
    label_alt: "{icon} {percent}% | {power}W | {time_remaining}"
    update_interval: 5000
    time_remaining_natural: False
    hide_unsupported: True
    charging_options:
      icon_format: "{charging_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 Copy Chapter

• 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.
• 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.
• callbacks: A dictionary specifying the callbacks for mouse events. It contains:
  • on_left: The name of the callback function for left mouse button click.
  • on_middle: The name of the callback function for middle mouse button click.
  • on_right: The name of the callback function for right mouse button click.
• 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 Copy Chapter

.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 Copy Chapter

.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;
}

File: docs/widgets/(Widget)-Bluetooth.md Copy Chapter

Bluetooth Widget Configuration

Shows Bluetooth status, connected devices, and a popup menu to browse paired/new devices.

You only need the minimal config below. Every option has a built-in default, omit anything you do not want to change. The full example later is a reference of those defaults, not something you must copy into your config.

Icons: Default icon glyphs (bar icons, popup device_icons, battery, scan) use Segoe Fluent Icons. Set font-family: 'Segoe Fluent Icons' in CSS for those elements, or override the icon strings in config if you prefer another icon font.

Minimal Configuration Copy Chapter

Add only the keys you care about. Everything else stays at the default.

bluetooth:
  type: "yasb.bluetooth.BluetoothWidget"
  options:
    label: "{icon} {device_count}"
    label_alt: "{icon} {device_name}"
    callbacks:
      on_left: "toggle_menu"
      on_right: "toggle_label"
    menu_config:
      blur: true
      alignment: "center"

Full Configuration Copy Chapter

Complete configuration for copy/paste or comparison. You do not need this block for a working widget, the minimal config already uses these values.

bluetooth:
  type: "yasb.bluetooth.BluetoothWidget"
  options:
    label: "{icon}"
    label_alt: "{icon}"
    class_name: ""
    label_no_device: "No devices connected"
    label_device_separator: ", "
    max_length: null
    max_length_ellipsis: "..."
    tooltip: true
    icons:
      bluetooth_on: "\ue702"
      bluetooth_off: "\ue702"
      bluetooth_connected: "\ue702"
    device_aliases: []
    keybindings: []
    callbacks:
      on_left: "toggle_menu"
      on_middle: "do_nothing"
      on_right: "do_nothing"
    menu_config:
      blur: true
      round_corners: true
      round_corners_type: "normal"
      border_color: "System"
      alignment: "right"
      direction: "down"
      offset_top: 6
      offset_left: 0
      labels:
        title: "Bluetooth"
        your_devices: "Your devices"
        new_devices: "New devices"
        not_connected: "Not connected"
        connected: "Connected"
        more_settings: "More Bluetooth settings"
        connect: "Connect"
        disconnect: "Disconnect"
        connecting: "Connecting"
        disconnecting: "Disconnecting"
        pair: "Pair"
        manage: "Manage"
        power_on: "On"
        power_off: "Off"
      device_icons:
        headphones: "\ue7f6"
        headset: "\ue95b"
        speaker: "\ue7f5"
        phone: "\ue8ea"
        tablet: "\ue70a"
        laptop: "\ue7f8"
        computer: "\ue950"
        keyboard: "\ue765"
        mouse: "\ue962"
        controller: "\ue7fc"
        watch: "\ue918"
        camera: "\ue722"
        generic: "\ue702"
        battery:
          empty: "\ueba0"
          low: "\ueba2"
          medium: "\ueba5"
          high: "\ueba8"
          full: "\uebaa"
        scan: "\ue72c"

Label placeholders Copy Section

Callbacks Copy Chapter

• toggle_menu - open/close the Bluetooth devices popup
• toggle_label - switch between label and label_alt
• exec cmd.exe /c start ms-settings:bluetooth - open Windows Bluetooth settings

Menu Config Copy Chapter

How it works Copy Section

The bar and popup talk to Windows Bluetooth APIs for radio power, the paired list, live connection status, battery when available, and scanning for new devices. Opening the popup refreshes your paired list (usually quick). The footer scan icon runs a real Bluetooth inquiry for nearby unpaired devices (that part is slower by nature).

Connect / Disconnect is different, and only applies to classic headphones, headsets, and speakers. Windows does not give apps a clean public “connect this headset” switch that works reliably for audio. What actually brings audio online or offline is the Bluetooth audio stack behind Core Audio: the same path Sound settings uses when an endpoint goes Active or Unplugged. The widget sends a short reconnect/disconnect oneshot to those audio endpoints (grouped as one physical device when Windows exposes a container id), then waits briefly until the endpoint state matches.

That is not loading or unloading drivers, and it is not ripping the adapter in and out. Nothing is installed or replaced. It asks the already-present Bluetooth audio filters to connect or disconnect, the way Windows itself does for that class of device.

Limitations worth knowing:

• Connect/Disconnect only targets classic audio devices (headphones / headset / speaker). Phones, keyboards, mice, controllers, and similar use Pair or Manage, which opens Windows Bluetooth settings pairing and profiles there are still Windows’ job.
• After you click Connect or Disconnect, the UI may wait a few seconds while Windows settles the audio endpoints. That delay is the stack catching up, not the widget spinning on purpose.
• Status in the list follows Windows connection events. Audio can look connected or disconnected a moment before or after the Bluetooth ACL flag flips, the widget prefers the live Bluetooth status for the row, and uses audio state mainly to know when a connect/disconnect action finished.

Available Style Classes Copy Chapter

.bluetooth-widget {}
.bluetooth-widget.your_class {}
.bluetooth-widget .widget-container {}
.bluetooth-widget .label {}
.bluetooth-widget .label.alt {}
.bluetooth-widget .icon {}

/* State classes are applied to both .icon and .label */
.bluetooth-widget .icon.bt-off,
.bluetooth-widget .label.bt-off {}
.bluetooth-widget .icon.bt-on,
.bluetooth-widget .label.bt-on {}
.bluetooth-widget .icon.bt-connected,
.bluetooth-widget .label.bt-connected {}

Available Style Classes for the Menu Copy Chapter

.bluetooth-menu {}
.bluetooth-menu .header {}
.bluetooth-menu .header .title {}
.bluetooth-menu .header .power-button {}
.bluetooth-menu .header .power-button:checked {}
.bluetooth-menu .header .progress-bar {}
.bluetooth-menu .error-message {}
.bluetooth-menu .bluetooth-list {}
.bluetooth-menu .section {}
.bluetooth-menu .section-title {}
.bluetooth-menu .bluetooth-item {}
.bluetooth-menu .bluetooth-item.active {}
.bluetooth-menu .bluetooth-item .icon {}
.bluetooth-menu .bluetooth-item .name {}
.bluetooth-menu .bluetooth-item .status {}
.bluetooth-menu .bluetooth-item .battery {}
.bluetooth-menu .bluetooth-item .battery-icon {}
.bluetooth-menu .bluetooth-item .battery-icon.empty {}
.bluetooth-menu .bluetooth-item .battery-icon.low {}
.bluetooth-menu .bluetooth-item .battery-icon.medium {}
.bluetooth-menu .bluetooth-item .battery-icon.high {}
.bluetooth-menu .bluetooth-item .battery-icon.full {}
.bluetooth-menu .bluetooth-item .controls-container {}
.bluetooth-menu .bluetooth-item .connect {}
.bluetooth-menu .footer {}
.bluetooth-menu .footer .settings-button {}
.bluetooth-menu .footer .scan-icon {}

Example Style Copy Chapter

/* Detailed source-code truncated for AI context efficiency. */

Preview of example above Copy Chapter

File: docs/widgets/(Widget)-Brightness.md Copy Chapter

Brightness Screen Widget Configuration

Displays your screen's brightness level and lets you adjust it on the fly. You can change brightness by scrolling your mouse wheel, click to cycle through set levels, and set up a timer to auto-adjust for day and night. It also supports an interactive menu where you can control the brightness and contrast of all your connected monitors at once.

Example Configuration Copy Chapter

brightness:
    type: "yasb.brightness.BrightnessWidget"
    options:
      label: "{icon}"
      label_alt: "Brightness {percent}%"
      tooltip: true
      hide_unsupported: true
      brightness_toggle_level: [0, 50, 100]
      auto_light: false
      auto_light_icon: "\udb80\udce1"
      auto_light_night_level: 35
      auto_light_night_start_time: "19:00"
      auto_light_night_end_time: "06:45"
      auto_light_day_level: 75
      brightness_icons: [
        "\udb80\udcde",  # Icon for 0-25% brightness
        "\udb80\udcdd",  # Icon for 26-50% brightness
        "\udb80\udcdf",  # Icon for 51-75% brightness
        "\udb80\udce0"   # Icon for 76-100% brightness
      ]
      brightness_menu:
        blur: true
        round_corners: true
        round_corners_type: "normal"
        border_color: "System"
        alignment: "right"
        direction: "down"
        brightness_icon: "\ue706"
        contrast_icon: "\ue7a1"
      callbacks:
        on_left: "toggle_brightness_menu"
        on_right: "toggle_label"

Description of Options Copy Chapter

• label: The format string for the label. You can use placeholders like {icon} or {percent} to dynamically insert information.
• label_alt: The alternative format string for the brightness widget. Useful for displaying additional information like percentage.
• tooltip: Whether to show the tooltip on hover.
• scroll_step: The step size for scrolling the brightness level. This value must be between 1 and 100.
• brightness_icons: A list of icons representing different brightness levels. The icons are used based on the current brightness percentage.
• hide_unsupported: Whether to hide the widget if the current system does not support brightness control.
• brightness_toggle_level: The brightness level to set when the widget is clicked.
• ddc_poll_interval: How often (seconds) to poll external DDC/CI monitors in the background. Range 0–600, default 60. Set 0 to disable background polling, opening the brightness menu still refreshes. Internal laptop brightness does not use this poll.
• brightness_menu: A dictionary specifying the menu settings for the widget. It contains the following keys:
  • blur: Enable blur effect for the menu.
  • round_corners: Enable round corners for the menu (this option is not supported on Windows 10).
  • round_corners_type: Set the type of round corners for the menu (normal, small) (this option is not supported on Windows 10).
  • border_color: Set the border color for the menu (this option is not supported on Windows 10).
  • alignment: Set the alignment of the menu (left, right).
  • direction: Set the direction of the menu (up, down).
  • offset_top: Set the top offset of the menu.
  • offset_left: Set the left offset of the menu.
  • brightness_icon: The icon to use for the brightness slider in the menu.
  • contrast_icon: The icon to use for the contrast slider in the menu.
• auto_light: Whether to automatically adjust the brightness icon based on the current brightness level.
• auto_light_icon: The icon to use when the auto_light option is enabled.
• auto_light_night_level: The brightness level at which the widget switches to the night.
• auto_light_day_level: The brightness level at which the widget switches to the day.
• auto_light_night_start_time: The time at which the night starts.
• auto_light_night_end_time: The time at which the night ends.
• callbacks: Callbacks for mouse events on the brightness widget. can be toggle_brightness_menu, toggle_label, toggle_level_next, toggle_level_prev, do_nothing.
• 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.

Example Style Copy Chapter

.brightness-widget {}
.brightness-widget .widget-container {}
.brightness-widget .widget-container .label {}
.brightness-widget .widget-container .icon {}

Style for the brightness popup menu Copy Chapter

.brightness-menu {
    background-color: rgba(36, 36, 36, 0.75);
    min-width: 300px;
}
/* Grouping for monitor rows including title and sliders */
.brightness-menu .monitor-row {
    background-color: rgba(139, 69, 19, 0);
    margin: 12px;
}
/* 
.monitor-0 is indexed as the first monitor row, 
adjust if you have multiple monitors and want to style them differently correctly.
*/
.brightness-menu .monitor-row.monitor-0 {
    margin-bottom: 0;
}
.brightness-menu .monitor-title  {
    font-size: 13px;
    font-weight: 600;
    color: #ffffff;
    margin-top: 4px;
}
.brightness-menu .monitor-subtitle {
    font-size: 11px;
    color: #a6adc8;
    margin-top: 2px;
    margin-bottom: 8px;
}
/* Container for the sliders to create a grouped appearance including icons and sliders */
.brightness-menu .slider-rows {
    background-color: rgba(255, 255, 255, 0.05);
    border-radius: 8px;
    padding: 16px; 
}
.brightness-menu .slider-icon {
    font-family: "Segoe Fluent Icons";
}
.brightness-menu .slider-row {
    margin: 4px 0;
    padding: 8px 0px;
}
/* optional styles for the brightness and contrast sliders */
.brightness-slider::groove {}
.contrast-slider::groove {}
.brightness-slider::handle{} 
.contrast-slider::handle{}

/* Brightness progress bar styles if enabled */
.brightness-widget .progress-container {}

Preview of the Widget Copy Chapter

File: docs/widgets/(Widget)-Cava.md Copy Chapter

Cava Widget Configuration

NOTE: This widget requires cava version >= 0.10.4 to be installed on your system. You can install the latest MSI from the Cava releases page. Cava needs to be accessible in the system PATH. After installing, fully stop YASB and start it again (do not use restart) so that YASB can pick up the new environment variables. If it still does not work, restart your PC.

Example Configuration Copy Chapter

cava:
    type: "yasb.cava.CavaWidget"
    options:
      bar_height: 12
      min_bar_height: 0
      gradient: 1
      foreground: "#89b4fa"
      gradient_color_1: '#74c7ec'
      gradient_color_2: '#89b4fa'
      gradient_color_3: '#cba6f7'
      bars_number: 8
      bar_spacing: 2
      bar_width: 4
      bar_type: "bars"
      framerate: 60
      hide_empty: true

Description of Options Copy Chapter

• class_name: Additional CSS class names for the widget container. (optional)
• source: Audio input source device. Set to "auto" (default) to use the system default audio device, or specify a device name to capture audio from a specific device. This is useful when you have multiple audio outputs and want to visualize a particular one. Requires cava >= 0.10.4 with device selection support.
• bar_height: The height of bars in pixels.
• min_bar_height: The minimum height of bars in pixels.
• bars_number: The number of bars to display. Can be between 0 and 512. 0 sets it to auto.
• output_bit_format: Binary bit format, can be '8bit' (0-255) or '16bit' (0-65530).
• orientation: The visual orientation of the bar. Can be 'top' (cava bars grow downwards) or 'bottom' (cava bars grow upwards). Default is 'bottom'.
• bar_spacing: Space between bars in number of characters.
• bar_width: Bars' width in number of characters.
• sleep_timer: Seconds with no input before cava goes to sleep mode. 0 to disable.
• sensitivity: Manual sensitivity in %. 200 means double height.
• lower_cutoff_freq: Lower cutoff frequencies for lowest bars.
• higher_cutoff_freq: Higher cutoff frequencies for highest bars.
• framerate: Accepts only non-negative values.
• noise_reduction: Noise reduction, 0-100. Higher = smoother but slower, lower = faster but noisier.
• channels: Visual channels. Can be 'stereo' or 'mono'.
• mono_option: Set mono to take input from 'left', 'right' or 'average'.
• reverse: Set to 1 to display frequencies the other way around.
• waveform: Show waveform instead of frequency spectrum, 1 = on, 0 = off.
• monstercat: Disables or enables the so-called "Monstercat smoothing" (spatial bar blending) with or without "waves". Set to 0 to disable.
• waves: Related to monstercat, 1 = on, 0 = off.
• foreground: Foreground color in hex format.
• gradient: Gradient mode, 1 = on, 0 = off.
• gradient_color_1: First gradient color in hex format.
• gradient_color_2: Second gradient color in hex format.
• gradient_color_3: Third gradient color in hex format. (optional)
• hide_empty: Hide widget when no audio is playing (requires sleep_timer to be enabled).
• bar_type: Type of bar display. Can be 'bars', 'bars_mirrored', 'waves', or 'waves_mirrored'.
• edge_fade: Apply fade effect to edges. Creates a smooth fade-out effect on the edges of the visualization. Can be configured in two ways:
  • Single value (e.g., 15): Applies the same fade width to both left and right edges
  • Array format (e.g., [10, 20]): Applies different fade widths - first value for left edge, second for right edge
  • Set to 0 or [0, 0] to disable. Important: When both sides have fade, each is automatically capped to half the widget width to prevent overlapping. When only one side has fade (e.g., [180, 0]), it can use the full widget width.
• callbacks: A dictionary specifying the callbacks for mouse events. The keys are on_left, on_middle, and on_right, and the values are the names of the callback functions.

Note: The waves and waves_mirrored ignore the bar_spacing option.

Allowed Callbacks: Copy Section

"reload_cava"
"do_nothing"

More information on this option is documented in the example config file

Style Copy Chapter

.cava-widget {
    padding: 0;
    margin: 0;
}
.cava-widget .widget-container {}

File: docs/widgets/(Widget)-Clock.md Copy Chapter

Clock Widget Configuration

Shows the current time in whatever format you like. You can cycle through different timezones, set up alarms, and open a built-in calendar that shows holidays and week numbers. The calendar can also show upcoming holidays for your country.

Example Configuration Copy Chapter

clock:
  type: "yasb.clock.ClockWidget"
  options:
    label: "{icon} {alarm} {%H:%M:%S}"
    label_alt: "\uf017 {%d-%m-%y %H:%M:%S}"
    locale: ""
    update_interval: 1000
    timezones: []
    icons:
      clock_01 : "\udb85\udc3f"
      clock_02 : "\udb85\udc40"
      clock_03 : "\udb85\udc41"
      clock_04 : "\udb85\udc42"
      clock_05 : "\udb85\udc43"
      clock_06 : "\udb85\udc44"
      clock_07 : "\udb85\udc45"
      clock_08 : "\udb85\udc46"
      clock_09 : "\udb85\udc47"
      clock_10 : "\udb85\udc48"
      clock_11 : "\udb85\udc49"
      clock_12 : "\udb85\udc4a"
      clock_16 : "SNACK TIME !"
      clock_21 : "Zzz..."
      clock_22 : "Zzz..."
      clock_23 : "Zzz..."
    alarm_icons:
      enabled: "\uf0f3"
      disabled: "\uf0a2"
      snooze: "\uf1f6"
    calendar: 
      blur: true
      round_corners: true
      round_corners_type: "normal"
      border_color: "system"
      alignment: "center"
      direction: "down"
      offset_top: 6
      offset_left: 0
      show_holidays: false
      show_week_numbers: true
      show_years: true
      country_code: "AR"
      holiday_color: "#FF6464"
      extended: false
    callbacks:
      on_left: "toggle_calendar"
      on_middle: "next_timezone"
      on_right: "toggle_label"

Description of Options Copy Chapter

• label: The format string for the clock. You can use placeholders like {%H:%M:%S}, {icon}, or {alarm} to dynamically insert time information and icons.
• label_alt: The alternative format string for the clock. Useful for displaying additional time details.
• class_name: Additional CSS class name for the widget. This can be used to apply custom styles.
• locale: The locale to use for the clock. If not specified, it defaults to an empty string.
• tooltip: Whether to show the tooltip on hover. When enabled, shows date, time, timezone, and active alarms information.
• update_interval: The interval in milliseconds to update the clock. Must be between 0 and 60000.
• timezones: A list of timezones to cycle through. If the value is empty, YASB will look up time zone info from the registry.
• icons: A dictionary mapping clock hours to icons. Keys are in the format clock_HH where HH is the hour in 24h format (00-23). By default, clock_13 to clock_23 reuse the icons from clock_01 to clock_11, unless explicitly defined.
• alarm_icons: A dictionary specifying icons for alarm states:
  • enabled: Icon shown when an alarm is enabled.
  • disabled: Icon shown when an alarm is disabled or in the active alarm popup.
  • snooze: Icon shown when an alarm is snoozed.
• calendar: A dictionary specifying the calendar settings for the widget. It contains the following keys:
  • blur: Enable blur effect for the calendar.
  • round_corners: Enable round corners for the calendar (this option is not supported on Windows 10).
  • round_corners_type: Set the type of round corners for the calendar (normal, small) (this option is not supported on Windows 10).
  • border_color: Set the border color for the calendar (this option is not supported on Windows 10).
  • alignment: Set the alignment of the calendar (left, right, center).
  • direction: Set the direction of the calendar (up, down).
  • offset_top: Set the offset from the top of the widget container.
  • offset_left: Set the offset from the left of the widget container.
  • country_code: The country code for holidays (e.g., "US", "AR").
  • subdivision: The subdivision code for holidays (e.g., "CA" for California, "Z" for Buenos Aires).
  • show_holidays: Whether to show holidays in the calendar.
  • holiday_color: The color used to highlight holidays in the calendar (hex format, e.g., "#00A300").
  • show_week_numbers: Whether to show week numbers in the calendar.
  • show_years: Whether to show the year label in the calendar popup.
  • extended: Show extended calendar with alarm/timer controls and upcoming holidays.
• callbacks: A dictionary specifying the callbacks for mouse events. The keys are on_left, on_middle, and on_right, and the values are the names of the callback functions. Available callbacks: toggle_calendar, next_timezone, toggle_label, context_menu, toggle_timer, toggle_alarm.

Clock format https://docs.python.org/3/library/time.html#time.strftime

Note about holidays:

• country_code specifies the country for which holidays are shown (e.g., "US" for United States, "AR" for Argentina). If you do not specify a country code, YASB will try to use the default country code based on your system settings.
• subdivision allows you to select a specific region or state within the country (e.g., "CA" for California, "Z" for Buenos Aires).
• For a full list of supported country codes and subdivisions, see the holidays available countries documentation.

Example Style Copy Chapter

/* Detailed source-code truncated for AI context efficiency. */

Example Style for the Calendar Copy Chapter

/* Detailed source-code truncated for AI context efficiency. */

Preview of the Widget Copy Chapter

File: docs/widgets/(Widget)-CPU.md Copy Chapter

CPU Widget Configuration

Keeps track of your processor's speed and usage in real-time. It supports per-core usage histograms, custom warning colors, and circular progress meters. You can click it to open a popup menu that shows detailed stats and performance graphs over time.

Example Configuration Copy Chapter

cpu:
  type: "yasb.cpu.CpuWidget"
  options:
    label: "\uf4bc {info[percent][total]}%"
    label_alt: "\uf437 {info[freq][current]} MHz"
    update_interval: 2000
    cpu_thresholds:
      low: 25
      medium: 50
      high: 90
    histogram_icons:
      - "\u2581" # 0%
      - "\u2581" # 10%
      - "\u2582" # 20%
      - "\u2583" # 30%
      - "\u2584" # 40%
      - "\u2585" # 50%
      - "\u2586" # 60%
      - "\u2587" # 70%
      - "\u2588" # 80%+
    histogram_num_columns: 8
    callbacks:
      on_left: "toggle_label"
      on_right: "toggle_menu"
    menu:
      enabled: true
      show_graph: true
      show_graph_grid: true
      graph_history_size: 60

Description of Options Copy Chapter

• label: The format string for the CPU usage label. You can use placeholders like {info[percent][total]} to dynamically insert CPU information.
• label_alt: The alternative format string for the CPU usage label. Useful for displaying additional CPU details.
• class_name: Additional CSS class name for the widget. This allows for custom styling.
• update_interval: The interval in milliseconds at which the widget updates its information. Minimum is 1000 ms (1 second).
• cpu_thresholds: A dictionary specifying the thresholds for CPU usage levels. The keys are low, medium, and high, and the values are the percentage thresholds.
• hide_decimal: Whether to hide decimal places in the CPU widget.
• histogram_icons: A list of icons representing different levels of CPU usage in the histogram. 8 icons are typically used, representing usage from 0% to 80%+.
• histogram_num_columns: The number of columns to display in the CPU usage histogram.
• callbacks: A dictionary specifying the callbacks for mouse events. The keys are on_left, on_middle, and on_right, and the values are the names of the callback functions.
• 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.
• menu: Configuration for the popup menu that displays a usage graph and detailed CPU statistics. It includes:
  • enabled: Whether the popup menu is enabled. Default: false.
  • blur: Whether to apply a blur effect to the popup background. Default: true.
  • round_corners: Whether the popup has rounded corners. Default: true.
  • round_corners_type: The type of rounded corners, either "normal" or "small". Default: "normal".
  • border_color: The border color of the popup. Default: "System".
  • alignment: Horizontal alignment of the popup relative to the widget: "left", "center", or "right". Default: "right".
  • direction: Whether the popup opens "up" or "down". Default: "down".
  • offset_top: Vertical offset in pixels from the widget. Default: 6.
  • offset_left: Horizontal offset in pixels from the widget. Default: 0.
  • show_graph: Whether to show the usage history graph. Default: true.
  • show_graph_grid: Whether to display a square grid overlay on the graph. Default: false.
  • graph_history_size: Number of data points to keep in the graph history. Must be between 10 and 180. Default: 60.
  • pin_icon: Icon displayed on the pin button when the popup is unpinned. Default: "\ue718".
  • unpin_icon: Icon displayed on the pin button when the popup is pinned. Default: "\ue77a".

Available Placeholders Copy Chapter

Core Information

• {info[cores][physical]} - Number of physical CPU cores
• {info[cores][total]} - Total number of CPU cores (including logical/hyperthreaded cores)

Frequency Information

• {info[freq][current]} - Current CPU frequency in MHz (includes turbo boost, matches Windows Task Manager)
• {info[freq][max]} - Base/nominal CPU frequency in MHz

Usage Percentages

• {info[percent][total]} - Total CPU usage percentage (0-100)
• {info[percent][core]} - List of per-core CPU usage percentages

Histograms

• {info[histograms][cpu_freq]} - CPU frequency histogram using configured icons
• {info[histograms][cpu_percent]} - CPU percentage histogram using configured icons
• {info[histograms][cores]} - Per-core usage histogram using configured icons

Note: The CPU widget uses Windows Performance Data Helper (PDH) API for accurate real-time metrics. If PDH counters are corrupted, the widget will display default values. To repair broken PDH counters, run lodctr /r as Administrator.

Example Style Copy Chapter

.cpu-widget {}
.cpu-widget .widget-container {}
.cpu-widget .widget-container .label {}
.cpu-widget .widget-container .label.alt {}
.cpu-widget .widget-container .icon {}

/* Status classes based on cpu_thresholds */
.cpu-widget .widget-container .label.status-low {}
.cpu-widget .widget-container .label.status-medium {}
.cpu-widget .widget-container .label.status-high {}
.cpu-widget .widget-container .label.status-critical {}

/* Icon status classes */
.cpu-widget .widget-container .icon.status-low {}
.cpu-widget .widget-container .icon.status-medium {}
.cpu-widget .widget-container .icon.status-high {}
.cpu-widget .widget-container .icon.status-critical {}

/* Progress bar styles (if enabled) */
.cpu-widget .progress-container {}

/* Custom class styling */
.cpu-widget.your-class-name {}
.cpu-widget.your-class-name .label {}

Popup Menu Styles Copy Section

.cpu-popup {
    background-color: rgba(28, 28, 28, 0.7);
    min-width: 400px;
}

.cpu-popup .header {
    background: transparent;
    padding: 12px 16px;
}
.cpu-popup .header .text {
    font-size: 16px;
    font-family: "Segoe UI";
    color: rgb(255, 255, 255);
}
.cpu-popup .header .pin-btn {
    font-size: 14px;
    background: transparent;
    font-family: "Segoe Fluent Icons";
    border: none;
    padding: 6px;
    color: rgba(255, 255, 255, 0.6);
}
.cpu-popup .header .pin-btn:hover {
    color: rgba(255, 255, 255, 0.6);
}
.cpu-popup .header .pin-btn.pinned {
    color: #ffffff;
}
/* Graph area */
.cpu-popup .graph-container {
    background:  transparent;
    min-height: 64px;
}
.cpu-popup .cpu-graph {
    color: #0f6bff;   /* <-- set the graph line/fill color */
}
.cpu-popup .cpu-graph-grid {
    color: rgba(255, 255, 255, 0.05);  /* set the grid line color */
}
.cpu-popup .graph-title {
    font-size: 12px;
    color: rgba(255, 255, 255, 0.5);
    font-family: 'Segoe UI';
    padding: 0px 0px 4px 14px;
}
/* Stats grid */
.cpu-popup .stats {
    background: transparent;
    padding: 16px;
}
.cpu-popup .stats .stat-item {
    background-color: rgba(255, 255, 255, 0.03);
    border: 1px solid rgba(255, 255, 255, 0.04);
    border-radius: 8px;
    padding: 8px 12px;
    margin: 8px;
}
.cpu-popup .stats .stat-label {
    font-size: 13px;
    color: rgba(255, 255, 255, 0.65);
    font-family: 'Segoe UI';
    font-weight: 400;
    padding: 6px 4px 2px 4px;
}
.cpu-popup .stats .stat-value {
    font-size: 20px;
    font-weight: 700;
    color: #ffffff;
    font-family: 'Segoe UI';
    padding: 0 4px 12px 4px;
}

Full CSS Example Copy Chapter

.cpu-widget {
    padding: 0 8px;
}

.cpu-widget .widget-container .label {
    font-size: 13px;
    color: #cdd6f4;
}

.cpu-widget .widget-container .icon {
    font-size: 14px;
    color: #89b4fa;
}

.cpu-widget .widget-container .label.status-low {
    color: #a6e3a1; /* Green */
}

.cpu-widget .widget-container .label.status-medium {
    color: #f9e2af; /* Yellow */
}

.cpu-widget .widget-container .label.status-high {
    color: #fab387; /* Orange */
}

.cpu-widget .widget-container .label.status-critical {
    color: #f38ba8; /* Red */
}

/* Progress bar customization */
.cpu-widget .progress-container {
    margin-right: 6px;
}

File: docs/widgets/(Widget)-Custom.md Copy Chapter

Custom Widget Configuration

A blank canvas for whatever data you want to put on your bar. You give it a command or script to run, and it displays the output - perfect for showing your IP address, GPU temperature, stock prices, or anything else you can fetch from a terminal command. Works with plain text or JSON.

Example Configuration to get IP Address Copy Chapter

ip_info:
  type: "yasb.custom.CustomWidget"
  options:
    label: "\udb81\udd9f {data[ip]}"
    label_alt: "\uf450 {data[city]} {data[region]}, {data[country]}"
    class_name: "ip-info-widget"
    tooltip: true
    tooltip_label: "IP: {data[ip]}\nCity: {data[city]}\nRegion: {data[region]}\nCountry: {data[country]}"
    exec_options:
      run_cmd: "curl.exe https://ipinfo.io"
      run_interval: 120000  # every 5 minutes
      return_format: "json"
      hide_empty: false
    callbacks:
      on_left: "toggle_label"
      on_middle: "exec cmd /c ncpa.cpl" # open network settings
      on_right: "exec cmd /c start https://ipinfo.io/{data[ip]} " # open ipinfo in browser

Example Configuration to get Nvidia Temp. Copy Chapter

nvidia_temp:
  type: "yasb.custom.CustomWidget"
  options:
    label: "{data}\udb81\udd04"
    label_alt: "{data}"
    class_name: "system-widget"
    exec_options:
      run_cmd: "powershell nvidia-smi --query-gpu=temperature.gpu --format=csv,noheader"
      run_interval: 10000 # run every 10 sec
      return_format: "string"
      hide_empty: false

Example Configuration to weather data Copy Chapter

nvidia_temp:
  type: "yasb.custom.CustomWidget"
  options:
    label: "London {data[current][temperature_2m]}{data[current_units][temperature_2m]}"
    class_name: "custom-widget"
    exec_options:
      run_cmd: "curl.exe http://api.open-meteo.com/v1/forecast?latitude=51.5074&longitude=-0.1278&current=temperature_2m&timezone=auto"
      run_interval: 1800000 # run every 30 min
      return_format: "json"
      hide_empty: false
      use_shell: false

Description of Options Copy Chapter

• label: The format string.
• label_alt: The alternative format string.
• label_placeholder: Placeholder text when data is not available. Default is "Loading...".
• label_max_length: The maximum length of the label. Minimum value is 1. Default is None.
• tooltip: Whether to show the tooltip on hover. Default is false.
• tooltip_label: Custom format string for the tooltip. Use {data} to reference the command output data. If not specified, shows the raw data representation (JSON for dict, string for other types).
• class_name: The CSS class name for the widget.
• exec_options: A dictionary specifying the execution options. The keys are:
  • run_cmd: The command or executable path to run. Default is None.
  • run_once: (boolean) If set to true, the command runs only once on startup and the repeat interval timer is disabled. Default is false.
  • run_interval: The repeat execution interval in milliseconds. Default is 120000 (2 minutes).
  • return_format: The format expected from the command output, either "json" or "string". Default is "json".
  • hide_empty: (boolean) If true, the widget hides itself when the output is empty or parsing fails. Default is false.
  • use_shell: (boolean) Whether to run the command inside a system shell. Default is true.
  • encoding: (string) Custom character encoding to decode the output (e.g., utf-8, cp1252). Default is None.
• callbacks: A dictionary specifying the callbacks for mouse events. The keys are on_left, on_middle, and on_right, and the values are the names of the callback functions.

Example Style Copy Chapter

.custom-widget {}
.custom-widget .widget-container {}
.custom-widget .widget-container .label {}
.custom-widget .widget-container .label.alt {}
.custom-widget .widget-container .icon {}