my quickshell config

a personal Hyprland desktop config built with Quickshell. status bar, app launcher, notification daemon, OSD, wallpaper manager, and a theme switcher with 206 themes. each piece is its own module and works independently, so feel free to grab only the parts you need.

i hope it's helpful as a starting point or reference. if you have questions or ide

as, don't hesitate to open an issue — happy to chat.

2026-03-10.16-57-33.mp4

what's included

Module	What it does
Bar	clock, workspaces, active window title, volume, brightness, network, battery, system tray, now-playing indicator
App Launcher	rofi drun-style application launcher
Notifications	dunst-style notification daemon with popups
OSD	on-screen display for volume and brightness changes, auto-hides
Theme Switcher	206 themes across 6 families, persists across restarts, or follow your wallpaper
Wallpaper Manager	grid picker for wallpapers, preview, supports hyprpaper and swww
Monitor Manager	visual hyprctl front-end for arranging, scaling, rotating, mirroring, and disabling displays

prerequisites

these are needed regardless of which modules you use:

• Quickshell + Qt 6
• Hyprland
• a Nerd Font (i use Hack Nerd Font — swap it in the QML files if you prefer another)

optional, depending on which modules you use:

• brightnessctl — for brightness display and control in the bar and OSD
• nmcli — for wifi network info in the bar
• /sys/class/power_supply/ — for battery info (standard on most laptops)
• hyprpaper or swww — for the wallpaper manager
• matugen or wallust — for generating a theme from your wallpaper
• hyprctl / Hyprland — for the monitor manager

installing everything

if you'd like the full setup:

git clone https://github.com/doannc2212/quickshell-config ~/.config/quickshell
quickshell

that's it — quickshell reads from ~/.config/quickshell/ by default.

installing individual modules

each module is self-contained in its own folder with a DefaultTheme.qml fallback, so you can pick and choose. here's how to set up just the parts you want.

bar

the status bar — clock, workspaces, window title, volume, brightness, network, battery, system tray, and a now-playing indicator.

extra dependencies: brightnessctl, nmcli, /sys/class/power_supply/

1. copy bar/ into your quickshell config directory
2. in your shell.qml, add:

import "bar"

Bar {}

the bar will use its built-in Tokyo Night Night colors by default. to wire it up with the theme switcher instead, pass theme: yourThemeObject.

you can also toggle the bar via IPC:

qs ipc call bar toggle

app launcher

a rofi drun-style launcher overlay. searches by name, description, keywords, and categories. keyboard navigation with arrow keys, enter, and escape.

1. copy app-launcher/ into your quickshell config directory
2. in your shell.qml, add:

import "app-launcher"

AppLauncher {}

3. bind a key in hyprland.conf:

bind = SUPER, D, exec, qs ipc call launcher toggle

notifications

a built-in notification daemon — replaces dunst/mako. popups appear in the top-right corner with urgency-based styling and auto-expire timers.

note: only one notification daemon can own org.freedesktop.Notifications on D-Bus at a time. please stop dunst/mako before using this.

1. copy notifications/ into your quickshell config directory
2. in your shell.qml, add:

import "notifications"

NotificationPopup {}

3. optionally bind IPC commands in hyprland.conf:

bind = SUPER, N, exec, qs ipc call notifications dismiss_all
bind = SUPER SHIFT, N, exec, qs ipc call notifications dnd_toggle

features:

• urgency-based accent colors (critical, normal, low)
• app icons for common apps (discord, firefox, spotify, etc.)
• action buttons from the notification
• progress bar showing time until auto-dismiss
• click to dismiss, close button per notification
• max 5 visible notifications at a time
• do not disturb mode

osd

a vertical pill overlay that appears on the right side of the screen when volume or brightness changes, then auto-hides after 1.5 seconds.

extra dependencies: brightnessctl

1. copy osd/ into your quickshell config directory
2. in your shell.qml, add:

import "osd"

OSD {}

no IPC needed — it reacts automatically to PipeWire volume changes and backlight changes.

theme switcher

a theme picker overlay with 206 themes across 6 families. selected theme persists across restarts and syncs with kitty terminal and system dark/light mode.

extra dependencies: gnome-themes-extra

1. copy theme-switcher/ into your quickshell config directory
2. in your shell.qml, create the switcher and wire its theme into other modules:

import "theme-switcher"

ThemeSwitcher {
    id: ts
}

// then pass ts.theme into your other modules:
// Bar { theme: ts.theme }
// AppLauncher { theme: ts.theme }

3. bind a key in hyprland.conf:

bind = SUPER, T, exec, qs ipc call theme toggle

4. add this to your kitty config so the theme switcher can update kitty colors:

allow_remote_control yes
listen_on unix:/tmp/kitty-{kitty_pid}
include theme-colors.conf

available theme families:

• Tokyo Night — Night, Storm, Moon, Light
• Catppuccin — Mocha, Macchiato, Frappe, Latte
• Zen — Dark, Light
• Arc — Dark, Light
• Beared — Arc, Surprising Eggplant, Oceanic, Solarized Dark, Coffee, Monokai Stone, Vivid Black
• MonkeyType — 187 community themes

theme from wallpaper

the switcher can generate a theme from an image instead of using a curated one.

extra dependencies: matugen or wallust — auto-detected (force one with WALLPAPER_THEME_TOOL=matugen|wallust).

generate a palette from an image and switch to it:

qs ipc call theme wallpaper /path/to/image.png

wallpaper mode persists across restarts and repaints the bar, launcher, notifications, kitty, and Hyprland borders. picking any curated theme in the switcher drops back out (the switcher's wallpaper toggle re-enters using the last palette).

generated palettes follow the image, so a low-contrast wallpaper may look flatter than the hand-tuned themes.

wallpaper manager

a grid-based wallpaper picker that scans ~/Pictures/Wallpapers and ~/Pictures. click to apply, right-click to preview. auto-detects swww or hyprpaper as backend. persists current wallpaper to wallpaper.conf.

extra dependencies: hyprpaper or swww

1. copy wallpaper/ into your quickshell config directory
2. in your shell.qml, add:

import "wallpaper"

WallpaperManager {}

3. bind a key in hyprland.conf:

bind = SUPER, W, exec, qs ipc call wallpaper toggle

monitor manager

an ARandR-style visual monitor editor for Hyprland. it queries hyprctl -j monitors all, draws the current layout, and lets you adjust resolution, scale, rotation, position, mirroring, and enabled state before applying a batched hyprctl keyword monitor ... layout. persists across reboots to ~/.config/hypr/monitors.conf.

1. copy monitor-manager/ into your quickshell config directory
2. in your shell.qml, add:

import "monitor-manager"

MonitorManager {}

3. bind a key in hyprland.conf:

bind = SUPER, O, exec, qs ipc call monitors toggle
bind = SUPER SHIFT, O, exec, qs ipc call monitors refresh

4. add this line to your hyprland.conf so your layout is restored on login:

source = ~/.config/hypr/monitors.conf

features:

• visual layout canvas with drag-to-arrange monitors
• per-output resolution, scale, rotation, position, enable/disable, and mirror controls

tweaking

• colors — all colors live in theme-switcher/Theme.qml. pick a theme via the switcher, or add your own by appending to the themes array.
• font — edit the default font: "Your Font" at the top of the entry file.
• layout — rearrange widgets in bar/Bar.qml.
• polling rate — change the interval in bar/SystemInfo.qml (default 2s).
• extra bar widgets — CPU, memory, and temperature widgets are already written in bar/Bar.qml but commented out. uncomment them if you'd like them back (requires top, free, and sensors).
• adding a module — create a folder with an entry QML file + DefaultTheme.qml, add property var theme: DefaultTheme {}, and wire it in shell.qml.

acknowledgments

this wouldn't exist without the wonderful work behind Quickshell, Hyprland, and the theme creators:

• Tokyo Night by enkia — 4 themes (Night, Storm, Moon, Light)
• Catppuccin by the Catppuccin team — 4 themes (Mocha, Macchiato, Frappe, Latte)
• Beared Theme by BeardedBear — 7 themes
• MonkeyType — 187 community themes. colors were derived from MonkeyType's theme palette. all credit goes to the original theme creators and the MonkeyType community contributors.

thank you all.