Skip to content

Customization

Jump to bottom
bitzzdev edited this page Aug 7, 2026 · 3 revisions

Customization

Understanding Auto-Generated Files

Files generated by wallust are marked with Auto-generated by wallust — DO NOT EDIT. These include:

  • ~/.config/waybar/style.css and config.jsonc
  • ~/.config/swaync/style.css
  • ~/.config/wlogout/style.css
  • ~/.config/rofi/theme-generated.rasi
  • ~/.config/rofi/themes/{launcher,power,wallpaper-grid}.rasi
  • ~/.config/rofi/icons/*.svg
  • ~/.config/kitty/colors.conf
  • ~/.config/cava/themes/generated
  • ~/.config/hypr/colors.lua and hyprlock.conf
  • ~/.config/qt6ct/qt6ct.conf, ~/.config/kdeglobals

Editing these directly works, but changes are overwritten on the next wallpaper change. To make permanent changes, edit the Jinja2 templates in ~/.config/wallust/templates/.

Changing Keybindings

All keybindings are in hypr/keybinds.lua using Hyprland's Lua API:

-- Add your own keybind
hl.bind("SUPER + SHIFT + Z", hl.dsp.exec_cmd("your-command"))

Standard modifiers: SUPER, SHIFT, CTRL, ALT. Hyprland hot-reloads Lua configs on save.

Adding Waybar Modules

  1. Add module to waybar/config.jsonc:
"custom/my-module": {
  "exec": "~/.config/waybar/scripts/my-script.sh",
  "interval": 10,
  "return-type": "json",
  "on-click": "some-command"
}

  1. Add it to modules-left, modules-center, or modules-right

  2. Style it in waybar/style.css (or waybar.css.j2 template for permanence):

#custom-my-module {
  color: @foreground;
  padding: 0 10px;
}
  1. Restart waybar: pkill -x waybar && waybar &

Custom Wallust Templates

Templates live in wallust/templates/. They use Jinja2 syntax:

background: {{background}}
foreground: {{foreground}}
accent: {{color1}}

Add a New Themed Component

  1. Create wallust/templates/myapp.conf.j2
  2. Register it in wallust/wallust.toml:
[myapp]
template = "myapp.conf.j2"
target = "~/.config/myapp/config"
  1. Add the target to WALLUST_OUTPUTS in wallust-cache-daemon.sh and wallpaper-select.sh (backup/restore lists)
  2. Add a reload step to reload-theme.sh if the app needs restarting
  3. Regenerate: wallust run ~/.cache/current_wallpaper.png --config-dir ~/.config/wallust

Rofi Themes

  • Static themes: 27 variants in rofi/themes/ — swap by changing @theme in rofi/config.rasi
  • Wallust themes: launcher.rasi, power.rasi, wallpaper-grid.rasi are regenerated from templates on every wallpaper change
  • Icons: 8 themed SVGs in rofi/icons/ (generated from *.svg.j2 templates)

SwayNC Notifications

Edit swaync/config.json for behavior and swaync/style.css for appearance (themed). After editing, reload: swaync-client --reload-css.

Adding Custom Scripts

  1. Create your script in scripts/ (or waybar/scripts/ for bar modules)
  2. Make it executable: chmod +x scripts/my-script.sh
  3. Add a keybind in hypr/keybinds.lua or a waybar module in waybar/config.jsonc

Script Best Practices

  • Use atomic mkdir for debounce if Hyprland-triggered (prevents double-firing)
  • Use pgrep for process guarding
  • Send notifications with notify-send
  • Keep polling intervals ≥ 5 seconds for performance

Adding System TUI Tools

To add a tool that opens in a floating terminal:

  1. Create a launcher script in waybar/scripts/: 
    #!/bin/bash
kitty --class system-tui -e your-tui-tool
  2. The existing window rule in hypr/rules.lua auto-floats anything with class system-tui
  3. Wire it to a waybar click or keybind

Disabling Components

Disable Waybar

Remove or comment out waybar & in hypr/autostart.lua.

Disable SwayNC

Remove swaync from hypr/autostart.lua.

Disable the Cache Daemon

systemctl --user stop wallust-cache-daemon.service
systemctl --user disable wallust-cache-daemon.service

Disable Animations

In hypr/animations.lua:

animations = { enabled = false }

Dark Theme (Default)

bitzdots enables dark theme across all apps out of the box:

  • GTK3/GTK4 — gtk/gtk-3.0/settings.ini + gtk-4.0/settings.ini set Adwaita with prefer-dark-theme=1 and Papirus-Dark icons
  • Qt5 — qt5ct/qt5ct.conf uses Breeze-Dark style
  • Qt6 — Auto-generated by wallust at ~/.config/qt6ct/qt6ct.conf with Breeze-Dark style and wallpaper-matched custom palette
  • Environment — environment.d/qt.conf sets QT_STYLE_OVERRIDE and QT_QPA_PLATFORMTHEME=qt6ct

To switch to light theme, edit the above files: Breeze-Dark → Breeze, Papirus-Dark → Papirus, prefer-dark-theme=1 → 0.

Custom Wallpaper Directories

By default, bitzdots uses:

  • ~/Pictures/Wallpapers/ (static images)
  • ~/Pictures/Wallpapers/live/ (video files)

Set a different directory before installing: WALLPAPER_DIR=/path ./install.sh, or edit the WALL_DIR variable in scripts/wallpaper-select.sh and wallust-cache-daemon.sh.

Restoring Defaults

cd ~/.config/bitzdots
./install.sh   # Re-links fresh configs

Color Scheme Options

Wallust generates 16 colors:

Variable Typical Use
{{background}} / {{color0}} Background
{{color1}} Red, errors, primary accent
{{color2}} Green, success
{{color3}} Yellow, warnings
{{color4}} Blue
{{color5}} Magenta
{{color6}} Cyan
{{color7}} Foreground / terminal white
{{color8}}-{{color15}} Bright/light variants

Clone this wiki locally