Skip to main content
Version: 2.1

wibox.widget.systray

Displays application icons through StatusNotifierItem over the session D-Bus. Applications that only support XEmbed do not appear. Items with status Passive are hidden.

Styling options​

AppearanceSettingsAvailable choices
Size and layoutbase_size, horizontal, reverseIcon size in pixels, row or column, reversed order.
Tray background and spacingbg_systray, systray_icon_spacing, systray_paddings, systray_max_rowsBackground, gaps, outer padding. One row; larger systray_max_rows values are not applied.
Icon imageicon_theme, per-application icon_overrideIcon-theme lookup. icon_override is not applied in this version.
Hoversystray_hover_bg, systray_hover_scaleBackground. Hover scaling is not applied in this version.
Attentionsystray_urgent_bg, systray_urgent_styleBackground. Dot, ring and glow indicators are not rendered in this version.
Application badgessystray_show_overlay, systray_overlay_*Show or hide; size; four corners; circle, rounded rectangle or rectangular background.
Per-application stylessystray_icon_styleExact ID/name rules or a function that returns a style table.
Context menussystray_menu_*Colours, border, font, dimensions and a callback to change menu entries.

A badge is an overlay image supplied by the application. An attention indicator is a dot, ring or border drawn by SomeWM. They have separate settings. This version can use a badge to trigger an attention background, but cannot replace it with a ring.

For screenshots and complete examples, see Customise the systray.

Constructor​

local wibox = require("wibox")
local beautiful = require("beautiful")

beautiful.systray_icon_spacing = 4

local tray = wibox.widget.systray()
tray:set_base_size(20)

wibox.widget.systray(reverse) returns the same widget on every call. The optional reverse argument defaults to false and is used only on the first call.

Properties​

SettingDefaultBehaviour
base_sizenilSquare icon size in pixels. nil uses 24 pixels.
horizontaltrueOrientation at construction. Set with wibox.widget.systray.set_horizontal(false) before the first constructor call for a vertical tray.
reversefalseReverses the item order.
screen"primary"Accepts a screen, "primary" or nil. The setter stores the value but does not filter the rendered icons by screen.

Use tray:set_base_size(size), tray:set_horizontal(boolean), tray:set_reverse(boolean) and tray:set_screen(screen). These settings belong to the shared instance. Each setter emits property::<name>.

For a tray on one monitor, include the widget only in that monitor's bar.

Theme variables​

These names are fields on beautiful, for example beautiful.systray_hover_bg = "#458588". Defaults below apply when the theme does not supply a value. Theme settings normally go after beautiful.init(...) and before bar creation.

Each setting lists its theme variable and, where supported, its Per-application key inside systray_icon_style. An omitted field inherits its theme variable. Settings marked Global only cannot be overridden through that table.

Tray, hover, attention and overlay backgrounds accept solid colours and gradients. Other Cairo patterns warn once and render transparent.

Tray layout​

SettingDefault and behaviour
bg_systray
Global only
Default: nil.
Tray background. Accepts a solid colour or gradient. Other patterns warn once and render transparent.
systray_icon_spacing
Global only
Default: 0.
Integer gap between icons, in pixels.
systray_paddings
Global only
Default: 0.
Integer outer padding on all sides, in pixels.
systray_max_rows
Global only
Default: 1.
Positive integer. Values above 1 warn once and still render as one row.

Icon images​

SettingDefault and behaviour
icon_theme
Global only
Default: "hicolor".
Icon-theme name used for icon-name lookup. Application pixmaps and icons found in the application's own icon directory take precedence.
icon_override
Per-application only
Default: nil.
Not applied in this version. In 1.4 and 2.0 this accepts a replacement image path or icon-theme name.

Hover​

SettingDefault and behaviour
systray_hover_bg
Per-application: hover_bg
Default: nil.
Background while the pointer is over the icon. nil means no global hover background.
systray_hover_scale
Per-application: hover_scale
Default: 1.0.
Not applied in this version. Values other than 1 warn once when hovered.

Attention indicators​

Attention styling appears when the item reports NeedsAttention. systray_overlay_triggers_urgent can also trigger it while an application overlay is present. Only the attention background is rendered in this version.

SettingDefault and behaviour
systray_urgent_bg
Per-application: urgent_bg
Default: nil.
Background while the item needs attention. When set, it takes precedence over the hover background.
systray_urgent_style
Per-application: urgent_style
Default: "none".
Not rendered in this version. The declared choices "none", "dot", "ring" and "glow" apply to 1.4 and 2.0.
systray_urgent_color
Per-application: urgent_color
Default: "#ff3333".
Not applied in this version. Indicator colour.
systray_urgent_outline_color
Per-application: urgent_outline_color
Default: "#ffffff".
Not applied in this version. Outline colour around the dot. Does not set the ring colour.
systray_urgent_position
Per-application: urgent_position
Default: "top_right".
Not applied in this version. Dot position: "top_left", "top_right", "bottom_left" or "bottom_right".
systray_urgent_size
Per-application: urgent_size
Default: 0.25.
Not applied in this version. Dot size. Numbers up to 1 are fractions of the icon size; larger numbers are pixels. Minimum 6 pixels in 1.4/2.0.
systray_urgent_shape
Per-application: urgent_shape
Default: gears.shape.circle.
Not applied in this version. Shape function (cr, width, height) for the dot and ring. Does not affect "glow".
systray_overlay_triggers_urgent
Per-application: overlay_triggers_urgent
Default: false.
Boolean. An application overlay triggers attention styling even if the item status is Active. Works when the overlay is hidden.
systray_icon_change_triggers_urgent
Per-application: icon_change_triggers_urgent
Default: false.
Not applied in this version. Icon changes do not trigger attention styling.

systray_show_overlay = false hides the badge. Combined with systray_overlay_triggers_urgent = true and systray_urgent_bg, the badge can trigger a background instead. Setting systray_urgent_style = "ring" has no effect in this version.

Application badges​

A badge is the item's overlay image. These settings do not create a badge or notification count. The application must supply the overlay.

SettingDefault and behaviour
systray_show_overlay
Global only
Default: true.
Boolean. Show or hide application overlays.
systray_overlay_position
Per-application: overlay_position
Default: "bottom_right".
"top_left", "top_right", "bottom_left" or "bottom_right".
systray_overlay_size
Per-application: overlay_size
Default: 0.33.
Number. Up to 1: fraction of the icon size. Above 1: pixels. Rounded to whole pixels.
systray_overlay_bg
Per-application: overlay_bg
Default: nil.
Background behind the overlay. nil draws no global background.
systray_overlay_shape
Per-application: overlay_shape
Default: "circle".
"circle", "rounded_rect" or "rect". Shapes the background, not the overlay image; has no visible effect without overlay_bg.
systray_overlay_padding
Per-application: overlay_padding
Default: 2.
Padding around the overlay within its background, in pixels. Used only when the background is set.

systray_overlay_triggers_urgent controls whether a badge also triggers attention styling. Hiding the badge does not disable that trigger.

Per-application styles​

beautiful.systray_icon_style defaults to nil. It accepts either:

  • A table mapping an exact item.id or item.app_name to a style table. The ID match takes precedence; the two matching tables are not merged.
  • A function function(item) returning a style table. Errors and non-table return values are ignored.

The style table accepts every key labelled Per-application above. It does not accept the global-only layout, menu or systray_show_overlay settings. Fields marked Not applied or Not rendered remain ineffective inside a per-application rule.

local beautiful = require("beautiful")

beautiful.systray_icon_style = {
["discord_status_icon_1"] = {
hover_bg = "#458588",
urgent_bg = "#cc241d",
overlay_position = "top_right",
overlay_triggers_urgent = true,
},
}

The ID is supplied by the tray item, not the window class. Find tray IDs shows the inspection command. Assigning another systray_icon_style table replaces the previous rules. false can disable a per-application boolean trigger even when its global value is true.

Context menus​

These variables style menus SomeWM builds from DBusMenu. They do not style menus drawn by the application itself. All are global-only. A missing systray menu value falls back to the corresponding beautiful.menu_* value, then the normal awful.menu defaults.

SettingFallback and behaviour
systray_menu_fg_normalFallback: beautiful.menu_fg_normal.
Colour of item text.
systray_menu_bg_normalFallback: beautiful.menu_bg_normal.
Menu background colour.
systray_menu_fg_focusFallback: beautiful.menu_fg_focus.
Colour of selected item text.
systray_menu_bg_focusFallback: beautiful.menu_bg_focus.
Selected item background colour.
systray_menu_border_colorFallback: beautiful.menu_border_color.
Menu border colour.
systray_menu_border_widthFallback: beautiful.menu_border_width.
Number. Border width in pixels.
systray_menu_fontFallback: beautiful.menu_font.
Pango font string, such as "sans 10".
systray_menu_widthFallback: beautiful.menu_width.
Number. Menu item width in pixels.
systray_menu_heightFallback: beautiful.menu_height.
Number. Menu item height in pixels.
systray_menu_callbackFallback: nil.
Function (item, menu_items) called before a DBusMenu is shown. Can edit menu_items or return a replacement table. Returning nil keeps the original table, including edits. Errors are ignored.

Interaction​

Left click activates an item, or opens its menu when the application marks it as a menu. Middle click requests secondary activation. Right click opens its menu. Scroll events are forwarded to the application. The application determines which actions it supports.

Tray source, icon styles and menus, renderer.