Skip to Content
Matuwall

Configuration

Every config key with its default

The config file is optional. Matuwall reads it once at startup:

$XDG_CONFIG_HOME/matuwall/config.toml
~/.config/matuwall/config.toml

Generate a complete one with every default:

matuwall --no-config --print-config > ~/.config/matuwall/config.toml

Every key is optional. An invalid value warns and uses the default. A syntax error ignores the whole file. There is no hot reload.

Starter Config

[general]
directory = "~/Pictures/Wallpapers"
backend = "awww"

[window]
preview = false
position = "bottom"
background = "#11111bcc"

[grid]
columns = 5
visible_rows = 1
carousel = true

[thumbnail]
width = 300
height = 169

[general]

KeyDefaultDescription
directory"~/Pictures/Wallpapers"Wallpaper directory, or an array of up to 8
recursivefalseAlso scan subdirectories. Hidden and symlinked ones are skipped
list""List file used instead of directory. "-" reads stdin
favorites"~/.config/matuwall/favorites.txt"File the f key adds to
backend"awww"awww, sweetbg, plasma, command or auto

Several directories:

directory = ["~/Pictures/Wallpapers", "~/Pictures/Photography"]

[window]

KeyDefaultDescription
previewfalseShow the selected wallpaper full-screen behind the panel
close_on_focus_lossfalseClose when keyboard focus leaves
close_on_applytrueClose after Enter applies
position"bottom"center, left, right, top or bottom
background"#11111bff"Panel color. "none" draws no panel
margin34Padding between tiles and panel edge
edge_margin24Gap between panel and monitor edge. Ignored at center
radius40Panel corner radius

Layer shell namespaces for compositor rules:

SurfaceNamespace
Panelmatuwall
Previewmatuwall-preview

[grid]

KeyDefaultRangeDescription
columns51..1024Max columns. In carousel mode, max visible tiles
visible_rows11..1024Max rows in the regular grid
carouseltruebooleanCentered single-axis strip
edge"auto"auto, clip, peek, fadeCarousel tiles at panel edges
sort"name"name, colorWallpaper order
spacing160..4096Gap between tiles
radius200..4096Tile corner radius
border_width00..4096Border width. 0 disables it
shadow_width120..4096Shadow fade width. 0 disables it
ring_width00..4096Selection ring width. 0 disables it

Matuwall may show fewer columns or rows to fit the monitor.

top, bottom and center use a horizontal strip. left and right use a vertical one.

edgeBehavior
clipCut tiles at the panel margin
peekLet tiles extend into the margin
fadeShrink and fade tiles as they leave
autofade when background is fully transparent, else clip

Sort by Color

sort = "color" orders by dominant hue, red to pink. Grey and black-and-white images come last.

  • Colors are learned in the background. The first launch shows name order
  • New wallpapers stay at the end until the next launch
  • Delete ~/.cache/matuwall/colors to relearn every color

[thumbnail]

KeyDefaultRangeDescription
width3001..16384Tile width in logical pixels
height1691..16384Tile height in logical pixels

[colors]

Colors use #rrggbb, #rrggbbaa or none.

KeyDefaultColors
tile"#313244ff"Placeholder tile
border"#585b70ff"Thumbnail border
shadow"#00000066"Thumbnail shadow
ring"#f2cdcdff"Selection ring
spinner"#cdd0e6ff"Loading dot

[animation]

KeyDefaultRangeDescription
navigation_ms4100..1000Navigation transition. 0 disables it
zoom_percent100..10Selected tile growth. 0 disables it

[input]

KeyDefaultDescription
mousefalseHover selects, wheel moves, left click applies

[backend.*]

SectionKeyDefaultDescription
[backend.awww]args[]Extra flags for awww
[backend.sweetbg]args[]Extra flags for sweetbg
[backend.plasma]args[]Extra flags for Plasma
[backend.command]apply""Custom setter command

See Backends.

[hooks]

KeyDefaultDescription
on_apply[]Commands run after a successful apply, up to 16

See Hooks.

On this page