Skip to Content
Kwybars
Configuration

Image Overlay

Draw a transparent image above the visualizer and match it to your wallpaper.

[image_overlay] draws one optional image above the visualizer. This is useful for Rainmeter-style compositions where transparent PNG artwork sits in front of bars, waves, or particles.

[image_overlay]
enabled = true
path = "~/.config/kwybars/overlays/mountain.png"
opacity = 1.0
fit = "contain"
width = 0
height = 0
offset_x = 0
offset_y = 0
KeyDescriptionDefaultAccepted values
enabledEnable image overlay drawing.falsetrue, false
pathImage file path. Absolute paths, ~/..., and paths relative to the active config file directory are supported. PNG, JPEG, and WebP files work.""string
opacityImage alpha multiplier.1.00.0..1.0
fitHow the image fits inside the target box."contain""contain", "cover", "stretch"
widthTarget image box width. 0 uses the current overlay width.0integer pixels
heightTarget image box height. 0 uses the current overlay height.0integer pixels
offset_xHorizontal offset from centered placement.0number pixels
offset_yVertical offset from centered placement.0number pixels

Notes:

  • The image is centered on the overlay area and is not limited to it. Set width and height larger than the overlay and the image reaches past it; with 0 it fits inside the overlay.
  • A bigger image grows equally on both sides of the center. Use offset_x and offset_y to move it, for example a negative offset_y to lift a tall image above a bottom overlay.
  • A monitor can have its own image through [output.NAME.image_overlay]. See Per-Monitor Settings.
  • Use transparent PNG artwork if you want the visualizer to remain visible around or behind the image.
  • Images larger than 40 megapixels are refused.
  • If the image cannot be read, the visualizer runs without it and the log says why. kwybars validate-config and kwybars doctor report it too.

Match Overlays to Wallpapers

kwybars image-overlay match picks the overlay image that matches your wallpaper's file name. See Config Switching.

On this page