Waybar Config Guide

Waybar is a status bar for Wayland compositors like Sway and Hyprland. It uses JSONC for configuration and CSS for styling. This guide covers waybar config file setup, module placement, and customization.

Install Waybar on Linux

Install Waybar using your distribution’s package manager.

On Debian and Ubuntu:

$ sudo apt install waybar

On Fedora:

$ sudo dnf install waybar

On Arch Linux:

$ sudo pacman -S waybar

Waybar Config File Location

Waybar searches for configuration files in this order:

Priority	Location
1	$XDG_CONFIG_HOME/waybar/config.jsonc
2	~/.config/waybar/config.jsonc
3	/etc/xdg/waybar/config.jsonc

Copy the default config to your home directory:

$ mkdir -p ~/.config/waybar
$ cp /etc/xdg/waybar/config.jsonc ~/.config/waybar/
$ cp /etc/xdg/waybar/style.css ~/.config/waybar/

Waybar Config Structure

The waybar config file uses key-value pairs in JSONC format. Three main arrays control module placement: modules-left, modules-center, and modules-right.

Basic Config Example

{
    "layer": "top",
    "position": "top",
    "modules-left": ["sway/workspaces", "sway/mode"],
    "modules-center": ["clock"],
    "modules-right": ["cpu", "memory", "battery"],
    "clock": {
        "format": "{:%H:%M}"
    },
    "battery": {
        "format": "{capacity}% {icon}",
        "format-icons": ["", "", "", "", ""]
    }
}

Common Settings

Key	Value	Description
layer	top/bottom	Bar appears above or below windows
position	top/bottom/left/right	Bar placement on screen
height	integer	Bar height in pixels
spacing	integer	Gap between modules in pixels

Configure Waybar Modules

Each module displays specific system information. Define modules after placing them in position arrays.

Clock Module

"clock": {
    "format": "{:%I:%M %p}",
    "format-alt": "{:%Y-%m-%d}",
    "tooltip-format": "{calendar}"
}

The format-alt key shows alternate text when clicked.

Battery Module

"battery": {
    "interval": 60,
    "states": {
        "warning": 30,
        "critical": 15
    },
    "format": "{capacity}% {icon}",
    "format-icons": ["", "", "", "", ""]
}

Workspaces Module

For Hyprland, use hyprland/workspaces instead of sway/workspaces:

"hyprland/workspaces": {
    "format": "{icon}",
    "on-click": "activate",
    "persistent-workspaces": {
        "*": 5
    }
}

Custom Modules

Create custom modules with the custom/ prefix:

"custom/power": {
    "format": "⏻",
    "on-click": "wlogout"
}

Style Waybar with CSS

The ~/.config/waybar/style.css file controls appearance. Target modules using CSS selectors.

* {
    font-family: "JetBrains Mono";
    font-size: 13px;
}

window#waybar {
    background: rgba(30, 30, 46, 0.9);
    color: #cdd6f4;
}

#clock {
    padding: 0 10px;
    color: #f9e2af;
}

#battery.warning {
    color: #fab387;
}

#battery.critical {
    color: #f38ba8;
}

CSS Selector	Target
window#waybar	Main bar container
#clock	Clock module
#battery	Battery module
#custom-power	Custom power module

Start Waybar Automatically

Add the autostart command to your compositor config.

For Hyprland, add to ~/.config/hypr/hyprland.conf:

exec-once = waybar

For Sway, add to ~/.config/sway/config:

bar {
    swaybar_command waybar
}

Reload Waybar after config changes:

$ pkill waybar && waybar &