Waybar — Highly Customizable Wayland Status Bar

Introduction

Waybar is a status bar designed for Wayland compositors such as Sway, Hyprland, and River. It renders as a panel at the top or bottom of your screen displaying system information through modular widgets. Every aspect of its appearance is styled via CSS, and its behavior is configured through a JSON file, giving users fine-grained control over layout, content, and look.

What Waybar Does

• Displays workspace indicators, window titles, and system tray icons for Wayland compositors
• Ships built-in modules for clock, battery, CPU, memory, disk, network, Bluetooth, PulseAudio, and backlight
• Supports custom modules that execute any shell script and display the output
• Renders using GTK3 and wlr-layer-shell, positioning itself correctly on multi-monitor setups
• Allows per-output (per-monitor) configuration with independent module sets

Architecture Overview

Waybar is written in C++ and links against GTK3 for rendering and the wlr-layer-shell-unstable Wayland protocol for anchoring itself to screen edges. Each module runs independently, polling or subscribing to system interfaces (D-Bus, sysfs, IPC sockets) at configurable intervals. Sway and Hyprland modules communicate over their respective IPC protocols to track workspaces and focused windows. The CSS theming engine supports transitions, gradients, and rounded corners, enabling visually rich bar designs.

Self-Hosting & Configuration

• Place your config at ~/.config/waybar/config.jsonc and styles at ~/.config/waybar/style.css
• Add exec waybar to your compositor config (e.g., ~/.config/sway/config)
• Define module arrays in modules-left, modules-center, and modules-right to control layout
• Set polling intervals per module with the interval key (in seconds)
• Build from source with meson build && ninja -C build && sudo ninja -C build install for the latest features

Key Features

• Full CSS theming with GTK3 for pixel-perfect customization of colors, fonts, and spacing
• Native IPC integration with Sway, Hyprland, River, and other wlroots-based compositors
• Custom modules let you display output from any script or command
• Multi-monitor aware with per-output configuration support
• Lightweight resource footprint suitable for tiling window manager setups

Comparison with Similar Tools

• Polybar — popular on X11 but does not support Wayland natively; Waybar is Wayland-first
• i3status / i3bar — simpler and less customizable; Waybar offers richer modules and CSS theming
• Eww (ElKowars Wacky Widgets) — widget system using a custom markup language; Waybar is simpler to configure via JSON/CSS
• yambar — minimal Wayland bar; Waybar has a larger community and more built-in modules
• swaybar — Sway's built-in bar; Waybar provides significantly more module types and styling options

FAQ

Q: Does Waybar work with compositors other than Sway? A: Yes. It works with any compositor that implements the wlr-layer-shell protocol, including Hyprland, River, and others.

Q: Can I use Waybar on X11? A: Waybar is designed for Wayland. For X11, consider Polybar or i3bar instead.

Q: How do I add a custom script module? A: Add a "custom/mymodule" entry to your config with "exec": "path/to/script" and it will display the script's stdout as the module content.

Q: Does Waybar support a system tray? A: Yes. Add the "tray" module to your config and it will display application tray icons using the StatusNotifierItem protocol.

Sources

• https://github.com/Alexays/Waybar
• https://github.com/Alexays/Waybar/wiki