trayer

Embed application windows into the system tray

TLDR

Run trayer

$ trayer

Position trayer to a specific edge

$ trayer --edge [left|right|top|bottom]

Provide a specific height and width of the panel (in pixels)

$ trayer --width [10] --height [32]

Provide the width of the panel in pixels or percentages

$ trayer --widthtype [pixel|percent] --width [72]

Align trayer to a specific direction

$ trayer --align [left|center|right]

Provide spacing between icons (in pixels)

$ trayer --iconspacing [10]

PARAMETERS

--edge <top|bottom|left|right>
    Position the tray along a specific screen edge.

--align <left|center|right>
    Align icons within the tray along the specified direction.

--width <pixels>
    Set a fixed width for the tray in pixels.

--widthtype <request|pixel|percent>
    Define how the tray's width is determined: based on icon requests, a fixed pixel value, or a percentage of screen width.

--height <pixels>
    Set a fixed height for the tray in pixels.

--heighttype <request|pixel|percent>
    Define how the tray's height is determined: based on icon requests, a fixed pixel value, or a percentage of screen height.

--margin <pixels>
    Set a margin (offset) from the screen edge.

--transparent <true|false>
    Enable or disable background transparency.

--alpha <0-255>
    Set the transparency level (0 for full transparency, 255 for opaque) when --transparent is true.

--tint <RRGGBB>
    Set the background color in hexadecimal RRGGBB format when transparency is disabled.

--monitor <num|primary|all>
    Specify which monitor to display the tray on (e.g., 0, 1, primary, or all).

--output <name|primary|all>
    Similar to --monitor, but uses Xrandr output names (e.g., DP-1, HDMI-0).

--distance <pixels>
    Set a distance in pixels from the edge specified by --distancefrom.

--distancefrom <top|bottom|left|right>
    Define which edge --distance should measure from.

--expand <true|false>
    Allow the tray to expand and fill available space along its edge.

--padding <pixels>
    Add padding around icons within the tray.

--SetDockType <true|false>
    Hint to the window manager that trayer should be treated as a dock.

--SetPartialStrut <true|false>
    Hint to the window manager about reserving screen space for the tray, preventing windows from overlapping it.

--hide-on-maximize <true|false>
    Hide the tray when a window is maximized.

--border <normal|none|solid|dot|dash>
    Set the style of the tray's border.

--border-width <pixels>
    Set the width of the tray's border.

--border-color <RRGGBB>
    Set the color of the tray's border in hexadecimal RRGGBB format.

--resize-app-icons <int>
    Resize all application icons to the specified square pixel size.

--align-center-icons <true|false>
    Vertically center application icons within the tray.

--verbose
    Enable verbose output for debugging.

--version
    Display the trayer version information and exit.

--help
    Display a help message with command-line options and exit.

DESCRIPTION

Trayer is a compact and minimalist GTK-based system tray application designed for Linux. It serves as a visual container for application icons that support the
freedesktop.org System Tray Protocol, commonly known as
XEmbed system tray icons. Often used in conjunction with lightweight window managers like Openbox, i3, or bspwm that do not provide their own integrated system tray, Trayer allows users to manage and interact with background applications such as network managers, chat clients, or media players directly from their desktop. It offers a high degree of customizability regarding its position, size, transparency, and appearance, making it flexible enough to blend seamlessly into various desktop environments and user preferences. Its primary goal is to provide essential system tray functionality without the overhead of a full-fledged desktop environment panel.

CAVEATS

Trayer relies on the EWMH (Extended Window Manager Hints) and the
freedesktop.org System Tray Protocol. Compatibility issues may arise with applications or window managers that do not fully adhere to these standards. Transparency features often require a running compositor (e.g., Picom, Compton) to function correctly; without one, the --transparent option may not yield the desired visual effect. While highly customizable, trayer's development is less active compared to full desktop environment panels, meaning new features or extensive bug fixes might be slower to arrive.

<B>COMMON USAGE EXAMPLE</B>

A typical way to launch trayer for a top-right, transparent setup:

trayer --edge top --align right --widthtype request --height 22 --margin 0 \
--transparent true --alpha 0 --SetDockType true --SetPartialStrut true \
--expand true --monitor primary --tint 0x000000 --padding 3

This command places trayer at the top-right corner, making it transparent and ensuring it occupies minimal space while hinting to the window manager about its presence.

<B>INTEGRATION WITH WINDOW MANAGERS</B>

To ensure trayer starts with your session, it's typically added to your window manager's autostart file (e.g., ~/.config/openbox/autostart for Openbox, or your ~/.xinitrc file if starting X manually). It's crucial to run it as a background process, often by appending an ampersand (&) to the command.

HISTORY

Trayer emerged as a solution for users of lightweight window managers who needed a system tray without the bloat of a full desktop environment. It provides a simple, dedicated space for application icons adhering to the XEmbed system tray specification. Its development has focused on maintaining core functionality and customization options, establishing it as a go-to choice for minimalists and users building custom desktop setups. It has remained a stable and reliable component for displaying system tray icons in various Linux environments over the years.