Configure Waybar: A clear status bar for Sway

A small clock and volume indicator are often enough to make a minimal desktop comfortable. My Waybar configuration in the Cthulhu repository is a useful starting point. It shows how a few settings become a status bar.

This tutorial assumes a running Sway session with Waybar installed. We will create separate test files and launch them from a terminal. Your existing bar remains in place while you learn how content and styling work. The Sway guide explains the desktop around it.

Two files with different jobs

The configuration is normally called config or config.jsonc under ~/.config/waybar/. JSONC describes content and behaviour and also permits comments. A CSS file controls fonts, colours and spacing.

Fix a wrong module list in the configuration. Fix an unreadable text colour in CSS. Waybar uses GTK CSS, so not every CSS property from a web browser works the same way here.

What does my published bar actually show?

The important lines in my example are:

"position": "top",
"output": "DP-1",
"modules-left": [],
"modules-center": ["clock"],
"modules-right": ["pulseaudio"]

The clock sits in the centre, volume on the right, and the bar appears on my DP-1 output. Adapt that monitor name or omit the selection. My clock shows seconds and opens gsimplecal when clicked; the volume display opens pavucontrol. Those applications must exist separately.

The file also defines network, CPU, temperature and memory settings. However, none is included in the visible module lists. A configured block alone therefore does not display anything. This distinction between configuration and visibility is essential.

Create a small test configuration

Create the configuration directory if needed:

mkdir -p ~/.config/waybar

Use your editor to save this complete JSON file as ~/.config/waybar/tutorial.jsonc. Choose another name if a personal file already exists there. The preview sits at the bottom and needs no Nerd Font icons:

{
  "layer": "top",
  "position": "bottom",
  "modules-center": ["clock"],
  "modules-right": ["pulseaudio"],
  "clock": {
    "format": "{:%H:%M}",
    "interval": 60
  },
  "pulseaudio": {
    "format": "Vol {volume}%",
    "format-muted": "Muted"
  }
}

Commas separate properties; there is no comma after the last property in an object here. The braces in {volume} belong to the audio module's format. The clock uses its own time-format placeholders.

The pulseaudio module uses that audio interface. A PipeWire system can supply it through PipeWire-Pulse. The module name does not automatically require a second, independent PulseAudio service.

Readable styling with Gruvbox-like colours

Save a second test file as ~/.config/waybar/tutorial.css:

* {
  font-family: sans-serif;
  font-size: 13px;
}

window#waybar {
  background: #282828;
  color: #ebdbb2;
}

#clock, #pulseaudio, #cpu {
  padding: 0 10px;
}

The dark background and light text fit my desktop's colour palette. A basic system font keeps this introduction independent of special icon fonts. #clock selects the clock module; these selectors refer to Waybar's elements.

Start with contrast and readability. Add colours, borders or effects individually afterwards. An elaborate bar is less useful if you can barely read its battery indicator or mute state.

Start and stop the preview

Launch the two files you just created:

waybar -c ~/.config/waybar/tutorial.jsonc -s ~/.config/waybar/tutorial.css

A clock and volume display should appear at the bottom. The terminal stays attached to this process and shows its messages. An additional bar can reserve screen space; this is a separate preview, not a second permanent startup bar.

Stop this preview with Ctrl + C in its terminal. Your normal bar remains. Save further edits and run the same preview command again. For a first experiment, this is easier to follow than terminating every Waybar process.

Exercise: Add a CPU display

Replace the right-hand module list in the test file with:

"modules-right": ["cpu", "pulseaudio"]

Add a CPU block at the same object level, remembering the separating comma before or after the new property:

"cpu": {
  "format": "CPU {usage}%",
  "interval": 2
}

On the next preview launch, a CPU percentage should appear before volume on the right. It is a short utilisation indicator rather than a complete diagnosis of a slow computer. To undo the change, remove cpu from the module list again; its unused settings can remain.

If a module or the entire bar is missing

• No bar: Check terminal output, file paths and whether you launched it inside the running Sway session.
• JSON error: Inspect commas, quotation marks and closed braces at the reported position.
• Missing module: Check its spelling in the visible list and availability in the installed Waybar build.
• No volume value: Inspect your audio stack and default output before changing colours.
• Boxes instead of icons: Check the font. Our text example avoids that dependency.

A wrong output name is another common cause when adopting configurations. The preview omits it deliberately. Within Sway, swaymsg -t get_outputs shows your actual outputs.

Privacy and moving from preview to daily use

The examples display local time, audio and CPU data. They need no cloud service. That does not automatically apply to every configuration you find: a custom module can run a script that fetches weather over the network, for example. Read those scripts too.

If you like the preview, back up your regular configuration and adopt the desired changes deliberately. Keep one appropriate startup command. My Sway file already launches Waybar, so additional entries can produce duplicate bars. For this exercise, Ctrl + C and keeping your original files provide the return path.

Example and reference material

My file and the Waybar documentation were reviewed on 7 October 2026. The test files here are deliberately simplified learning examples.

• My Waybar configuration
• Its accompanying stylesheet
• Waybar configuration and visible modules
• Waybar GTK CSS
• Waybar clock module and time formatting