A visual configuration editor for Waybar — build, style and preview your bar in real time.
No more editing JSON and CSS by hand. Design your Waybar with live feedback, templates and full module control.
Available on the AUR as
vswaybar-studio. Single-file Python 3 + GTK3 application.
vsWaybar Studio is built for people who want a great-looking, functional Waybar without having to learn JSON, CSS and the Waybar wiki from scratch.
If you are new to Hyprland or tiling window managers, the default Waybar setup can feel overwhelming: a JSON config file, a separate CSS file, cryptic module keys, format strings, and a restart cycle just to see any change. vsWaybar Studio removes that friction — you pick a template, adjust colors and modules visually, hit Apply, and you have a working bar.
This tool is not meant to replace hand-crafted configs. If you already know Waybar well and maintain a complex setup with custom scripts, named instances, grouped modules and per-module CSS overrides, you will quickly hit the edges of what the editor can do. That is by design — the goal is a smooth on-ramp, not a full IDE.
What vsWaybar Studio does handle gracefully: it reads your existing config on startup, preserves any blocks it does not recognize, and writes them back untouched. So you can use it alongside a manually edited config without losing anything.
- Live bar preview — a thin strip at the top mirrors your actual Waybar in real time; always visible, never scrolls away
- Bar settings — position, output/monitor, height, spacing, margins, layer
- Visual styles — Bar (solid), Islands (floating zones), Modules (per-pill)
- Layout editor — drag modules between Left / Center / Right zones for both bar and dock
- Module config — click any module to edit its specific settings (format, intervals, on-click actions, colors, animations…)
- User Commands — add unlimited custom launcher modules: choose an icon from a Nerd Font glyph picker, set a color and an on-click command; they appear in the bar as clickable icons
- Styling — edit all 14 CSS color tokens, font, opacity, border-radius, padding
- Templates — 54 ready-made themes across 36 color palettes and 3 visual styles; apply with one click
- Palette tools — load from image via matugen, or generate a random palette
- Scripts editor — edit
weather.pyand other custom scripts in-place - Automatic backups — every apply creates a timestamped backup of your config, CSS and scripts
- Lazy tab loading — only the active tab is built at startup; remaining tabs load on first visit for fast startup
- Dark / Light editor theme toggle
- Apply writes
config+style.cssto disk and restarts Waybar automatically
- Python 3.10+
python-gobject(GTK3 bindings)python-cairowebkit2gtk-4.1— bar live preview- Waybar
Optional:
- matugen — palette generation from wallpaper image (Styling tab)
These are not installed by vsWaybar Studio — install them only if you use the corresponding module.
| Module | Package needed | Install |
|---|---|---|
custom/bar-cpu custom/bar-mem custom/bar-vol custom/bar-wifi |
vsbar.py (bundled) |
Modules tab → Install script button |
custom/claudebar |
claudebar (AUR) |
yay -S claudebar |
custom/weather |
weather.py (bundled) + OpenWeatherMap API key |
Scripts tab → save script; free key at openweathermap.org |
custom/updates |
pacman-contrib |
sudo pacman -S pacman-contrib |
custom/swaync |
swaync |
yay -S swaync |
custom/power |
wlogout |
yay -S wlogout |
pulseaudio on-click |
pavucontrol |
sudo pacman -S pavucontrol |
network / custom/bar-wifi on-click |
nm-connection-editor |
sudo pacman -S network-manager-applet |
hyprland/workspaces hyprland/window |
Hyprland compositor | hyprland.org |
yay -S vswaybar-studio
# or
paru -S vswaybar-studiogit clone https://github.com/victorsosaMx/vsWaybar-Studio
cd vsWaybar-Studio
chmod +x vswaybar-studio
./vswaybar-studioThe editor reads ~/.config/waybar/config and ~/.config/waybar/style.css on startup.
Apply writes both files back and restarts Waybar.
The weather module uses weather.py — a script that queries the OpenWeatherMap API.
A free API key is required (no credit card needed).
- Go to openweathermap.org and create a free account
- Go to API Keys in your profile → copy your key
- The free tier includes current weather data (more than enough)
Open vsWaybar Studio → Modules tab → select Weather from the list.
Fill in:
- API Key — paste your OpenWeatherMap key
- City — your city name (e.g.
Monterrey,New York,Madrid) - Units —
metric(°C) orimperial(°F)
Click Save weather.conf. This writes ~/.config/waybar/weather.conf with your settings.
The API key is stored only in that file — it is never included in the script itself.
Go to the Scripts tab → select Weather fetcher → click Save script.
This writes weather.py to ~/.config/waybar/scripts/weather.py with execute permissions.
Click Apply in the header. Waybar will restart and the weather module will appear in the bar.
Note: The script interval defaults to 3600 seconds (1 hour). On first run it may take a moment to fetch. If you see no weather data, verify your API key is valid and your city name is spelled correctly.
The updates module (custom/updates) shows the number of pending system updates using checkupdates from pacman-contrib.
sudo pacman -S pacman-contribThe updates module opens a terminal to run the actual update. By default it uses Kitty:
sudo pacman -S kittyIf you prefer a different terminal, go to Modules → Updates and change the On click command.
Go to Modules tab → select Updates from the list.
You can change:
- On click — the command that runs when you click the module (e.g. open a terminal with
yayorflatpak update) - Interval — how often to check for updates (default: 3600 seconds)
Click Apply. The updates count will appear in the right side of the bar.
Note:
checkupdateschecks onlypacmanpackages. For AUR packages, edit the script in the Scripts tab to also runyay -Quaor similar.
User Commands are custom launcher modules — a clickable icon in the bar that runs a command when clicked.
Go to Modules → scroll down to the User Commands section → click + Add.
Enter a short name (letters and hyphens only, e.g. spotify, terminal, files). The module key will be custom/<name>.
- Icon — click Choose icon… to pick a glyph from the Nerd Font library (~96 icons)
- Color — pick a color using the color button or type a hex value
- On click — the command to run (e.g.
spotify,kitty,nautilus) - Tooltip text — optional hover label
Go to the Layout tab → drag custom/<name> into the Left, Center or Right zone.
Click Apply. The icon appears in the bar and clicking it runs your command.
To remove a User Command: Modules tab → select it → click − Remove. It is removed from the bar and all zones immediately.
Every save operation (Apply, Save as…, Save script, Save script as…) automatically backs up your current files to:
~/.config/waybar/backups/
20260321_143022_config
20260321_143022_style.css
20260321_143022_weather.py
...
Backups are timestamped — you can always roll back by copying a backup file over the original.
| Palette | Source |
|---|---|
| Catppuccin Mocha / Latte / Macchiato / Frappe | catppuccin/catppuccin |
| Dracula | dracula/dracula-theme |
| Nord / Nord Light | nordtheme/nord |
| Gruvbox Dark / Light | morhetz/gruvbox |
| Tokyo Night | folke/tokyonight.nvim |
| One Dark | atom/one-dark-ui |
| Rosé Pine | rose-pine/rose-pine-theme |
| Everforest | sainnhe/everforest |
| Kanagawa | rebelot/kanagawa.nvim |
| Solarized Dark / Light | altercation/solarized |
| Monokai | monokai.pro |
| GitHub Dark | primer/primitives |
Forest Night, Forest, Forest Daylight, Mario, Mario Dark, Luigi Dark, Vader, Cyberpunk Neon, Cyberpunk Yellow, Anime, Aurora Borealis, Carnage, Hello Kitty, Tux, Sand, Ubuntu Dark, Ice Mint, Retro Paper.
This project is built on top of amazing open-source work:
Runtime
- Waybar by Alexis Rouillard — the status bar this editor configures
- Hyprland by Vaxry — the Wayland compositor
- GTK3 / PyGObject — GUI toolkit and Python bindings
- PyCairo — 2D graphics for the bar preview
Tools integrated
- matugen by InioX — material-you palette generator from wallpaper
- SwayNotificationCenter by Erik Reider — notification center (
custom/swayncmodule) - wlogout — Wayland logout / power menu (
custom/powermodule) - Kitty by Kovid Goyal — terminal emulator used by the updates module
- JetBrains Mono Nerd Font — icons used throughout the bar modules
Module app integrations (default on-click actions — all configurable)
- ML4W Calendar (
com.ml4w.calendar) — calendar app launched from the clock module - Mousam by Amit Sharma (
io.github.amit9838.mousam) — weather app launched from the weather module - NetworkManager /
nm-connection-editor— network settings launched from the network module - pavucontrol — PulseAudio volume control launched from the audio module
- pacman-contrib (
checkupdates) — used by the updates module to count pending packages - OpenWeatherMap API — weather data source for
weather.py(free API key required) - vsFetch — system info fetcher launched from the arch logo module
Color palettes
- Catppuccin — Soothing pastel theme framework
- Dracula — Dark theme for everything
- Nord — Arctic, north-bluish color palette
- Gruvbox by Pavel Pertsev — retro groove color scheme
- Tokyo Night by Folke Lemaitre
- One Dark — Atom's iconic dark theme
- Rosé Pine — Soho vibes for the technically minded
- Everforest by sainnhe — Green-based warm color scheme
- Kanagawa by rebelot — Inspired by the colors of the famous painting
- Solarized by Ethan Schoonover — Precision colors for machines and people
- Monokai by Wimer Hazenberg — The original dark color scheme
MIT — do whatever you want, credit appreciated.
Made with GTK3 and too much caffeine.