Systray Widget

Popup Options

Example Configuration

systray:
  type: "yasb.systray.SystrayWidget"
  options:
    class_name: "systray"
    label_collapsed: "▼"
    label_expanded: "▶"
    label_position: "left" # Can be "left" or "right"
    icon_size: 16 # Can be any integer between 8 and 64
    pin_click_modifier: "alt" # Can be "ctrl", "alt" or "shift"
    show_unpinned: true
    show_unpinned_button: true
    show_battery: false
    show_volume: false
    show_network: false
    use_hook: false # Whether to use the new systray hook instead of the legacy systray monitor
    hide_icons: [] # Optional, list of process names to hide (e.g. ["discord"])
    btn_shadow:
      enabled: true
      color: "black"
      radius: 3
      offset: [ 1, 1 ]

Example Popup Mode Configuration

When show_in_popup is enabled, unpinned icons are shown in a popup grid (similar to Windows) instead of inline in the bar. Pinned icons remain in the bar.

systray:
  type: "yasb.systray.SystrayWidget"
  options:
    class_name: "systray"
    label_collapsed: "▼"
    label_expanded: "▶"
    label_position: "right"
    icon_size: 16
    pin_click_modifier: "alt"
    show_in_popup: true
    icons_per_row: 4
    popup:
      blur: true
      round_corners: true
      round_corners_type: "normal"
      border_color: None
      alignment: "center"
      direction: "down"
      offset_top: 6
      offset_left: 0

Note on Shadows

container_shadow is applied to the container if it's not transparent. If it is transparent, container shadows will be applied to the child container and buttons instead. This can cause double shadows if you already have shadows applied to the child container and buttons. Apply the shadows only to the container that is actually visible.

Systray Widget Limitations:

There are some limitations with the systray widget:

• Systray widget will not show icons for apps if they ignore "TaskbarCreated" message. Meaning that if the original developers decided to ignore this message - their systray icons will not be shown. It's rare, but there are such cases (NVIDIA App for example). This is NOT a YASB bug.
• In rare cases systray icon might ignore click events if the original application was already running before YASB was started. Example: Epic Games Launcher. No solution for this so far.

Systray Hook vs Monitor

The systray hook is a more reliable and performant way to monitor systray icons. However, since it's an explorer.exe process hook (dll injection) it can potentially have some issues with Defender or other AV programs. Setting use_hook: false will completely bypass this method and revert back to the original systray monitor window method that is much less intrusive, but has plenty of compatibility issues with other apps. If your AV blocks the dll (or deletes it) systray widget will automatically use legacy mode.

Description of Options

• class_name: The class name for the base widget. Can be changed if multiple systray widgets need to have different styling.
• label_collapsed: Label used for the collapse button when unpinned container is hidden.
• label_expanded: Label used for the collapse button when unpinned container is shown.
• label_position: The position of the button that collapses unpinned container.
• icon_size: The size of the icons in the systray. Can be any integer between 8 and 64.
• pin_click_modifier: The modifier key used to pin/unpin icons. Can be "ctrl", "alt" or "shift".
• show_unpinned: Whether to show unpinned container on startup.
• show_unpinned_button: Whether to show the 'collapse unpinned icons' button.
• show_in_popup: When enabled, unpinned icons are shown in a popup grid (like Windows system tray overflow) instead of inline. Clicking the expand/collapse button opens the popup. Pinned icons remain in the bar.
• icons_per_row: Number of columns in the popup icon grid. Only used when show_in_popup is true. Can be 1–12.
• popup: Popup window appearance settings. Only used when show_in_popup is true. See Popup Options table above.
• show_battery: Whether to show battery icon (from the original systray).
• show_volume: Whether to show volume icon (from the original systray).
• show_network: Whether to show network icon (from the original systray).
• hide_icons: A list of process names to hide from the systray. Each entry is matched exactly (case-insensitive) against the executable name without extension. For example, to hide Discord set hide_icons: ["discord"] which matches Discord.exe.
• tooltip: Whether to show tooltips when hovering over systray icons.
• use_hook: Whether to use the systray hook. Default is false. False will use legacy systray monitor, true will use the new systray hook.
• container_shadow: Container shadow options.
• unpinned_shadow: Unpinned container shadow options.
• pinned_shadow: Pinned container shadow options.
• unpinned_vis_btn_shadow: Unpinned visibility button shadow options.
• btn_shadow: Systray button (icons) shadow options.

Debug Options

Show unpinned button has a right click menu that allows you to refresh the systray icons.

Style

.systray {} /* The base widget style */
.systray .widget-container {} /* Style for the widget container */
.systray .unpinned-container {} /* Style for container with unpinned systray icons */
.systray .pinned-container {} /* Style for container with pinned systray icons */
.systray .pinned-container[forceshow=true] {} /* Style for pinned container when it is forced to show during dragging operation */
.systray .button {} /* Style for the individual systray buttons/icons */
.systray .button.dragging {} /* Style for the icon currently being dragged */
.systray .button.drag-over {} /* Style for the icon being hovered over during a drag */
.systray .pinned-container.drop-target {} /* Style for the pinned container when it is an empty drop target */
.systray .unpinned-visibility-btn {} /* Style for the 'collapse unpinned icons' button */
.systray-popup {} /* Style for the popup window (when show_in_popup is true) */
.systray-popup-container {} /* Style for the popup grid container (when show_in_popup is true) */

Example CSS

.systray {
    background: transparent;
    border: none;
    margin: 0;
}
.systray .unpinned-container {
    background: transparent;
}
.systray .pinned-container {
    background: transparent;
}
.systray .button {
    border-radius: 4px;
    padding: 2px;
}

.systray .button:hover {
    background: rgba(255, 255, 255, 0.2);
}
/* Icon being dragged, we already apply some transparency to it so you don't need to use it */
.systray .button.dragging {}

.systray .button.drag-over {
     background: rgba(255, 255, 255, 0.4);
}

.systray .pinned-container.drop-target {
    background: rgba(255, 255, 255, 0.1);
}
.systray .unpinned-visibility-btn {
    border-radius: 4px;
    height: 20px;
    width: 16px;
    border: none;
    outline: none;
}

.systray .unpinned-visibility-btn:checked {
    background: transparent;
}

.systray .unpinned-visibility-btn:hover {
    background: rgba(255, 255, 255, 0.1);
}

/* Popup styles (when show_in_popup is true) */

/* The icon the drag is hovering over (drop target icon) */
.systray-popup .button.drag-over {
    background-color: rgba(255, 255, 255, 0.2);
}
/* Icon being dragged, we already apply some transparency to it so you don't need to use it */
.systray-popup .button.dragging {}

.systray .pinned-container.pinned-container.drop-target {
    background-color: rgba(255, 255, 255, 0.1);
}
.systray-popup {
    background-color: rgba(48, 48, 48, 0.6);
    padding: 4px;
}
.systray-popup .button {
    padding: 10px;
    margin: 0;
    border: 0;
    border-radius: 6px;
}
.systray-popup .button:hover {
    background-color: rgba(255, 255, 255, 0.05);
}