Quick answer: what a good Waybar config includes
A good Waybar config includes clear modules, readable CSS, documented dependencies, compositor-specific notes, fonts, icons, and screenshots that show normal desktop states. Waybar is often the most visible part of a Linux rice, but it is also one of the easiest pieces to break with missing scripts or fonts.
Start with status bar dotfiles, compare Hyprland dotfiles, and use the dotfiles marketplace to inspect complete examples. If you are building a full rice, read Linux Dotfiles Stack Teardown and The 2026 Linux Ricing Guide.
Example 1: minimal Waybar config
Use a minimal bar when you want stability and low maintenance.
{
"layer": "top",
"position": "top",
"modules-left": ["hyprland/workspaces"],
"modules-center": ["clock"],
"modules-right": ["network", "pulseaudio", "battery"]
}
Best for:
- New Hyprland users.
- Laptop setups where reliability matters.
- Rices where the wallpaper and terminal carry the visual style.
This setup needs very few scripts, which makes it easy to copy between machines.
Visual example: minimal bar anatomy
A minimal Waybar theme should still communicate state clearly. The visual goal is not to remove information. It is to remove decoration that does not help you make decisions.
| Zone | Suggested modules | Visual treatment |
|---|---|---|
| Left | Workspaces, active window | Strong active state, quiet inactive state |
| Center | Clock or current mode | Centered, readable, no tiny text |
| Right | Network, audio, battery, tray | Compact modules with clear warning colors |
In a screenshot, a minimal bar should show active workspace contrast, a normal clock state, and at least one right-side status module. If every module uses the same color and weight, the bar may look clean but become hard to scan. If every module has a different background, it can look busy even with only five modules.
For real daily use, test three states: no active window title, a very long window title, and a low-battery or disconnected-network state. A bar that survives those states is usually better than one tuned for a single perfect screenshot.
Example 2: laptop Waybar config
A laptop bar should prioritize battery, network, brightness, volume, and thermal awareness.
{
"modules-left": ["hyprland/workspaces", "hyprland/window"],
"modules-center": ["clock"],
"modules-right": ["backlight", "pulseaudio", "network", "battery", "tray"],
"battery": {
"format": "{capacity}% {icon}",
"format-icons": ["BAT", "BAT", "BAT", "FULL"]
}
}
When you download a laptop-focused Waybar setup, check whether brightness controls assume brightnessctl, light, or compositor-specific commands.
Example 3: media-focused Waybar config
Media modules make a desktop feel polished, but they often depend on MPRIS players and custom scripts.
{
"modules-left": ["hyprland/workspaces"],
"modules-center": ["mpris"],
"modules-right": ["pulseaudio", "network", "clock"]
}
Best for:
- Music-heavy desktop rices.
- Screenshot-focused setups.
- Users who want player state visible at a glance.
Before copying, confirm the module works with your player and does not poll too aggressively.
Example 4: rice-focused Waybar config
Rice-focused bars usually combine custom CSS, icons, modules, and compositor integrations.
{
"layer": "top",
"position": "top",
"height": 34,
"spacing": 8,
"modules-left": ["custom/launcher", "hyprland/workspaces"],
"modules-center": ["hyprland/window"],
"modules-right": ["custom/weather", "pulseaudio", "battery", "clock"]
}
This is where visual polish lives, but also where breakage hides. Custom weather, media, clipboard, and update modules often call shell scripts. Read those scripts before installing.
Waybar themes by desktop style
Different Linux rices need different bar behavior. A Hyprland setup with animated gaps may want a floating pill bar. A Niri setup may need clearer workspace context. A Sway setup may favor i3-like predictability. Match the bar to the workflow before copying the CSS.
| Desktop style | Good Waybar pattern | Avoid |
|---|---|---|
| Hyprland visual rice | Floating modules, accent active workspace, matching launcher palette | Overusing blur if the compositor already has heavy effects |
| Sway workstation | Straight top bar, simple workspace labels, reliable tray | Script-heavy widgets that fail on older packages |
| Niri workflow | Clear focused window and workspace/module separation | Hyprland-only modules copied without testing |
| Laptop rice | Battery, backlight, network, power profile, tray | Hiding critical battery warnings for aesthetics |
| Terminal-first setup | Clock, workspace, audio, network, minimal media | Large decorative widgets that steal vertical space |
When you browse status bar dotfiles, check whether the showcase names the compositor. A config can look generic but still call Hyprland-specific modules under the hood. That is fine for Hyprland, but it should be documented.
How to test a downloaded Waybar config
Before replacing your real config, run Waybar against a temporary folder:
mkdir -p /tmp/waybar-test
cp config style.css /tmp/waybar-test/
waybar -c /tmp/waybar-test/config -s /tmp/waybar-test/style.css
Then watch the terminal output. Missing icons, unknown modules, failed scripts, and JSON parse errors usually appear there. If a custom module calls a script, open the script before running the bar for a long session.
Useful checks:
- Confirm the config is valid JSON or JSONC.
- Confirm custom scripts are executable only when needed.
- Search for hardcoded
/home/usernamepaths. - Check whether icons require a specific Nerd Font.
- Test with laptop battery unplugged if the theme includes battery styling.
- Test on a narrow screen if you use a laptop or vertical monitor.
Common Waybar config mistakes
Most Waybar problems are small mismatches between the screenshot and the actual machine. Missing fonts make icons disappear. Missing scripts make custom modules show blank output. Hyprland-only modules fail on Sway or Niri. Laptop modules fail on desktops without batteries. Weather and update widgets fail when API keys, package managers, or network commands are assumed.
When a theme looks broken, simplify before rewriting it. Disable custom modules, start Waybar with only workspaces, clock, network, audio, and battery, then add pieces back one at a time. This makes the failure obvious and keeps a nice bar from turning into a mystery debugging session.
Good shared Waybar dotfiles also include screenshots for normal, warning, and empty states so users can verify behavior before installing.
Waybar CSS checklist
- Define font family and fallback font.
- Keep module padding consistent.
- Use readable contrast for active workspaces.
- Avoid tiny text on high-resolution displays.
- Keep hover and warning states visible.
- Document icon font requirements.
- Test with empty, long, and error states.
FAQ
Is Waybar only for Hyprland?
No. Waybar is commonly used with Hyprland and Sway, and many configs also support Niri or other Wayland workflows depending on modules.
Why does my Waybar config show missing icons?
Most missing icons come from missing Nerd Fonts or icon fonts. Check the font-family in style.css and install the expected font.
Can I download Waybar themes?
Yes. Browse status bar dotfiles and inspect whether the theme includes config, CSS, scripts, fonts, and screenshots.
What makes a Waybar config unsafe?
The main risk is not Waybar itself. The risk is custom scripts that run commands, read private paths, install packages, or assume the creator's machine layout.
Should I use Waybar or AGS?
Use Waybar if you want a stable, config-driven status bar. Use AGS if you want a more programmable desktop shell and are comfortable maintaining JavaScript or TypeScript widgets.