Configuration

VibePanel works out of the box with sensible defaults. Create a config file to customize behavior or style it with theming.

Config File

The configuration uses TOML format and is named config.toml.

Config files are searched in order:

1. $XDG_CONFIG_HOME/vibepanel/config.toml
2. ~/.config/vibepanel/config.toml
3. ./config.toml (current directory)

Use --config <path> to specify an explicit path.

To get started with a config file:

mkdir -p ~/.config/vibepanel
vibepanel --print-example-config > ~/.config/vibepanel/config.toml

There is also a minimal example at the bottom of this page.

Changes reload instantly, just save and see your changes immediately.

[bar]

Option	Type	Default	Description
position	string	"top"	Bar position: "top", "bottom", "left", or "right"
size	integer	32	Bar height in pixels (all sizes scale from this)
spacing	integer	8	Space between widgets (pixels)
screen_margin	integer	0	Distance from screen edge (pixels)
inset	integer	8	Distance from bar edge to first/last widget
padding	integer	4	Vertical padding inside the bar (pixels)
border_radius	integer	30	Corner roundness (% of bar height)
popover_offset	integer	1	Gap between widgets and popovers
outputs	array	[]	Limit bar to specific outputs (empty = all)
background_color	string		Override bar background (CSS color)
background_opacity	float	0.0	Bar background opacity (0.0-1.0)
outline	bool		Override theme.outline for the bar (true = force, false = suppress, omit = inherit)

Size: This value is the base for scaling - fonts, icons, and padding all scale proportionally.

Multi-monitor: By default, VibePanel displays on all monitors and handles hot-plug automatically. Use outputs to limit to specific monitors. To find output names: hyprctl monitors (Hyprland), niri msg outputs (Niri), or wlr-randr.

[widgets]

Option	Type	Default	Description
left	array	["workspaces", "window_title"]	Widgets on the left
center	array	["media"]	Widgets in the center
right	array	["tray", "updates", "cpu", "quick_settings", "battery", "clock", "notifications"]	Widgets on the right
border_radius	integer	40	Widget corner roundness (% of widget height)
background_color	string		Override widget background (CSS color)
background_opacity	float	1.0	Widget background opacity (0.0-1.0)
popover_background_opacity	float		Override popover background opacity (0.0-1.0). Default: max of bar and widget opacity
outline	bool		Override theme.outline for widgets (true = force, false = suppress, omit = inherit)

Widgets can be grouped to share a background:

right = [
  "tray",
  { group = ["cpu", "memory"] },
  "notifications",
]

Non-merged widget groups (widgets that don't share a popover) now paint each widget's own background color independently. Merge groups (widgets that open the same popover, like cpu + memory) still render as a single button and inherit the first widget's color.

See Widgets for all available widgets, per-widget options, and more spacer examples.

[theme]

Option	Type	Default	Description
mode	string	"dark"	Theme mode (see below)
accent	string	"#adabe0"	"gtk", "none", or hex color. In auto mode, derives from wallpaper unless set explicitly
animations	bool	true	Enable/disable all CSS transitions and animations
ripple	bool	true	Enable/disable Material Design ripple effect on click
shadows	bool	true	Enable/disable box-shadows on popovers. Disable to prevent blur artifacts with compositor blur
scheme	string		Material You polarity: "dark", "light", or "gtk" (auto mode only). "gtk" follows the GTK/system light/dark preference while keeping wallpaper-derived colors. Omit to derive from wallpaper luminance
popover	string		Popover color polarity override: "dark" or "light". Runs popovers on the specified scheme regardless of the bar's theme
wallpaper	string		Explicit wallpaper path for auto mode. Supports ~ expansion (default: auto-detect from wallpaper daemon)
blur	bool	false	Enable panel-controlled blur via ext-background-effect-v1 Wayland protocol
outline	bool	false	Decorative CSS border on bar, widgets, and popover surfaces
outline_width	integer	1	Outline width in pixels (0-4; 0 disables it visibly)
outline_color	string	"accent"	Outline color: "subtle", "accent", "foreground", or hex color
outline_opacity	float	1.0	Outline opacity (0.0-1.0)

Theme modes:

• auto - Derive a Material You palette from your wallpaper (detects hyprpaper, swww/awww, wpaperd, waypaper)
• gtk - Derive colors from your GTK theme
• dark / light - Fixed dark or light theme

Icons ([theme.icons]):

Option	Type	Default	Description
theme	string	"material"	"material" (bundled) or "gtk" (system theme)
weight	integer	400	Material icon stroke weight (100-700, lower = thinner)

The weight option only applies when using theme = "material".

State colors ([theme.states]):

Option	Type	Default
warning	string	"#e5c07b"
urgent	string	"#ff6b6b"

Typography ([theme.typography]):

Option	Type	Default
font_family	string	"monospace"
font_scale	float	0.6

font_scale accepts values between 0.1 and 1.0.

See Theming for full theming reference.

[audio]

Option	Type	Default	Description
allow_overdrive	bool	false	Allow output and microphone volume above 100%, capped at PulseAudio's recommended UI maximum

[weather]

Shared weather data settings used by the Weather widget and by clock popovers with show_weather = true.

Option	Type	Default	Description
auto_locate	bool	false	Resolve location automatically when no explicit location is configured
location	string		City or place name to geocode
latitude	float		Explicit latitude
longitude	float		Explicit longitude
units	string	"metric"	"metric" or "imperial"
wind_units	string		"km/h", "mph", or "m/s". Default: m/s for metric, mph for imperial
refresh_interval	integer	900	Refresh interval in seconds. Minimum: 600

Use either location, or both latitude and longitude.

[osd]

On-screen display for volume, brightness, and other system changes.

Option	Type	Default	Description
enabled	bool	true	Enable/disable OSD
position	string	"bottom"	"bottom", "top", "left", or "right"
timeout_ms	integer	1500	How long OSD stays visible (milliseconds)
show_value	bool	false	Show current numeric value next to the bar

[advanced]

Option	Type	Default	Description
compositor	string	"auto"	"auto", "hyprland", "niri", "sway", "miracle", "scroll", or "mango"
pango_font_rendering	bool	false	Use Pango instead of CSS for font rendering

Compositor backend: When set to auto (default), VibePanel detects your compositor by checking for HYPRLAND_INSTANCE_SIGNATURE, then NIRI_SOCKET, SWAYSOCK, MIRACLESOCK, and MANGO_INSTANCE_SIGNATURE, before falling back to Mango. The "sway" backend also covers Miracle WM and Scroll.

Pango font rendering: Enable pango_font_rendering = true if you see clipped glyphs or font sizing issues in layer-shell surfaces.

Layer Shell Namespaces

Each surface has a unique namespace that compositors can use for window rules (blur, opacity, animations, etc.):

Surface	Namespace
Bar	vibepanel
Tooltip	vibepanel-tooltip
Notification toast	vibepanel-toast
OSD overlay	vibepanel-osd
Click catcher	vibepanel-click-catcher
Widget popovers	vibepanel-<widget>-popover

CLI Commands

Command	Description
vibepanel --print-example-config	Print example config with common options
vibepanel --check-config	Validate config and exit

See CLI for the full command reference.

Custom CSS

Place style.css beside the active config file. Relative @import paths resolve from the importing stylesheet, and imported local files hot reload. See CSS for search paths, variables, classes, and examples.

Minimal Example

[bar]
size = 32
background_opacity = 1.0

[widgets]
left = ["workspaces", "window_title"]
center = ["media"]
right = ["quick_settings", "battery", "clock", "notifications"]

[theme]
mode = "auto"

More Examples

Islands Look (Transparent Bar)

[bar]
background_opacity = 0.0

[widgets]
background_opacity = 1.0

Solid Bar

[bar]
border_radius = 0
background_opacity = 1.0
background_color = "#1a1a2e"

Limit to Specific Monitor

[bar]
outputs = ["eDP-1"]

Edge-to-Edge Bar

[bar]
screen_margin = 0
border_radius = 0