A modern Wayland desktop shell built with Quickshell and designed specifically for the niri compositor. Features Material 3 design principles with a heavy focus on functionality and customizability.

Screenshots

View More

Application Launcher

System Monitor

Lock Screen

Dynamic Theming

Notification Center

Dock

What's Inside

Core Widgets:

TopBar: fully customizable bar where widgets can be added, removed, and re-arranged.
- App Launcher with fuzzy search, categories, and auto-sorting by most used apps.
- Workspace Switcher Dynamically resizing niri workspace switcher.
- Focused Window Displays the currently focused window app name and title.
- Media Player Short form media player with equalizer, song title, and controls.
- Clock Clock and date widget
- Weather Weather widget with customizable location
- System Tray System tray applets with context menus.
- Process Monitor CPU/Ram usage indicators - with a detailed process list PopUp
- Power/Battery Power/Battery widget for battery metrics and power profile changing.
- Notifications Notification bell with a notification center popup
- Control Center High-level view of network, bluetooth, and audio status
Spotlight Launcher A central app launcher/search that can be triggered via an IPC keybinding.
Central Command A combined music, weather, calendar, and events PopUp.
Process List A process list, with system metrics and information. More detailed modal available via IPC.
Notification Center A center for notifications that has support for grouping.
Dock A dock with pinned apps support, recent apps support, and currently running application support.
Control Center A full control center with user profile information, network, bluetooth, audio input/output, and display controls.
Lock Screen Using quickshell's WlSessionLock

Features:

Dynamic wallpaper-based theming with matugen integration
Numerous IPCs to trigger actions and open various modals.
Calendar integration with khal
Audio/media controls
Grouped notifications
Brightness control for internal and external displays
Qt and GTK app theming synchronization, as well as Ghostty auto-theme support.

Installation

Quick Start

Dependencies:

# Arch Linux
paru -S quickshell-git ttf-material-symbols-variable-git inter-font ttf-fira-code

# Fedora  
sudo dnf copr enable errornointernet/quickshell && sudo dnf install quickshell-git
# Install fonts manually (see instructions below)

Get the shell:

# Arch linux available via AUR
paru -S dankmaterialshell-git

# Manual install
mkdir -p ~/.config/quickshell
git clone https://github.com/bbedward/DankMaterialShell.git ~/.config/quickshell/DankMaterialShell
qs -c DankMaterialShell

Detailed Setup

Font Installation

Material Symbols (Required):

# Manual installation
mkdir -p ~/.local/share/fonts
curl -L "https://github.com/google/material-design-icons/raw/master/variablefont/MaterialSymbolsRounded%5BFILL%2CGRAD%2Copsz%2Cwght%5D.ttf" -o ~/.local/share/fonts/MaterialSymbolsRounded.ttf
fc-cache -f

# Arch Linux
paru -S ttf-material-symbols-variable-git

Typography (Recommended):

# Inter Variable Font
curl -L "https://github.com/rsms/inter/releases/download/v4.0/Inter-4.0.zip" -o /tmp/Inter.zip
unzip -j /tmp/Inter.zip "InterVariable.ttf" "InterVariable-Italic.ttf" -d ~/.local/share/fonts/
rm /tmp/Inter.zip && fc-cache -f

# Fira Code
curl -L "https://github.com/tonsky/FiraCode/releases/download/6.2/Fira_Code_v6.2.zip" -o /tmp/FiraCode.zip
unzip -j /tmp/FiraCode.zip "ttf/*.ttf" -d ~/.local/share/fonts/
rm /tmp/FiraCode.zip && fc-cache -f

Optional Features

Enhanced Functionality:

# Arch Linux
pacman -S cava wl-clipboard cliphist ddcutil brightnessctl qt5ct qt6ct
paru -S matugen

# Fedora
sudo dnf install cava wl-clipboard ddcutil brightnessctl qt5ct qt6ct
sudo dnf copr enable wef/cliphist && sudo dnf install cliphist
sudo dnf copr enable heus-sueh/packages && sudo dnf install matugen

What you get:

matugen: Wallpaper-based dynamic theming
ddcutil: External monitor brightness control
brightnessctl: Laptop display brightness
wl-clipboard: Required for copying various elements to clipboard.
qt5ct/qt6ct: Qt application theming
cava: Audio visualizer
cliphist: Clipboard history

Usage

Niri Integration

Add to your niri config

spawn-at-startup "qs" "-c" "DankMaterialShell"

// Dank keybinds
// 1. These should not be in conflict with any pre-existing keybindings
// 2. You need to merge them with your existing config if you want to use these
// 3. You can change the keys to whatever you want, if you prefer something different
// 4. For the increment/decrement ones you can change the steps to whatever you like too
binds {
   Mod+Space hotkey-overlay-title="Application Launcher" {
      spawn "qs" "-c" "DankMaterialShell" "ipc" "call" "spotlight" "toggle";
   }
   Mod+V hotkey-overlay-title="Clipboard Manager" {
      spawn "qs" "-c" "DankMaterialShell" "ipc" "call" "clipboard" "toggle";
   }
   Mod+M hotkey-overlay-title="Task Manager" {
      spawn "qs" "-c" "DankMaterialShell" "ipc" "call" "processlist" "toggle";
   }
   Mod+Comma hotkey-overlay-title="Settings" {
      spawn "qs" "-c" "DankMaterialShell" "ipc" "call" "settings" "toggle";
   }
   Super+Alt+L hotkey-overlay-title="Lock Screen" {
      spawn "qs" "-c" "DankMaterialShell" "ipc" "call" "lock" "lock";
   }
   XF86AudioRaiseVolume allow-when-locked=true {
      spawn "qs" "-c" "DankMaterialShell" "ipc" "call" "audio" "increment" "3";
   }
   XF86AudioLowerVolume allow-when-locked=true {
      spawn "qs" "-c" "DankMaterialShell" "ipc" "call" "audio" "decrement" "3";
   }
   XF86AudioMute allow-when-locked=true {
      spawn "qs" "-c" "DankMaterialShell" "ipc" "call" "audio" "mute";
   }
   XF86AudioMicMute allow-when-locked=true {
      spawn "qs" "-c" "DankMaterialShell" "ipc" "call" "audio" "micmute";
   }
   XF86MonBrightnessUp allow-when-locked=true {
      spawn "qs" "-c" "DankMaterialShell" "ipc" "call" "brightness" "increment" "5";
   }
   XF86MonBrightnessDown allow-when-locked=true {
      spawn "qs" "-c" "DankMaterialShell" "ipc" "call" "brightness" "decrement" "5";
   }  
}

IPC Commands

Control everything from the command line, or via keybinds:

# Audio control
qs -c DankMaterialShell ipc call audio setvolume 50
qs -c DankMaterialShell ipc call audio mute

# Launch applications  
qs -c DankMaterialShell ipc call spotlight toggle
qs -c DankMaterialShell ipc call processlist toggle

# System control
qs -c DankMaterialShell ipc call wallpaper set /path/to/image.jpg
qs -c DankMaterialShell ipc call theme toggle
qs -c DankMaterialShell ipc call lock lock

# Media control
qs -c DankMaterialShell ipc call mpris playPause
qs -c DankMaterialShell ipc call mpris next

Theming

System App Integration

GTK Apps: Install Colloid or similar Material theme:

./install.sh -s standard -l --tweaks normal

Configure in ~/.config/gtk-3.0/settings.ini:

[Settings]
gtk-theme-name=Colloid

Qt Apps:

# Install Breeze
pacman -S breeze breeze5  # Arch
sudo dnf install breeze  # Fedora

# Configure qt5ct/qt6ct
echo 'style=Breeze' >> ~/.config/qt5ct/qt5ct.conf

Dynamic Theming: Enable wallpaper-based theming in Settings → Appearance → System App Theming after installing matugen.

Terminal Integration

Ghostty users can add automatic color theming:

echo "config-file = ./config-dankcolors" >> ~/.config/ghostty/config

Calendar Setup

Sync your Google Calendar for dashboard integration:

Configuration Steps

Install dependencies:

# Arch
pacman -S vdirsyncer khal python-aiohttp-oauthlib

# Fedora  
sudo dnf install python3-vdirsyncer khal python3-aiohttp-oauthlib

Configure vdirsyncer (~/.vdirsyncer/config):

[general]
status_path = "~/.calendars/status"

[pair personal_sync]
a = "personal"
b = "personallocal"
collections = ["from a", "from b"]
conflict_resolution = "a wins"
metadata = ["color"]

[storage personal]
type = "google_calendar"
token_file = "~/.vdirsyncer/google_calendar_token"
client_id = "your_client_id"
client_secret = "your_client_secret"

[storage personallocal]
type = "filesystem"
path = "~/.calendars/Personal"
fileext = ".ics"

Setup sync:

vdirsyncer sync
khal configure

# Auto-sync every 5 minutes
crontab -e
# Add: */5 * * * * /usr/bin/vdirsyncer sync

Configuration

All settings are configurable in ~/.config/DankMaterialShell/settings.json, or more intuitively the built-in settings modal.

Key configuration areas:

Widget positioning and behavior
Theme and color preferences
Time format, weather units and location
Light/Dark modes
Wallpaper and Profile picture
Dock enable/disable and various tunes.

Troubleshooting

Common issues:

Missing icons: Verify Material Symbols font installation with fc-list | grep Material
No dynamic theming: Install matugen and enable in settings
Qt apps not themed: Configure qt5ct/qt6ct and set QT_QPA_PLATFORMTHEME
Calendar not syncing: Check vdirsyncer credentials and network connectivity

Getting help:

Check the issues for known problems
Share logs from qs -c DankMaterialShell for debugging
Join the niri community for compositor-specific questions

Contributing

DankMaterialShell welcomes contributions! Whether it's bug fixes, new widgets, theme improvements, or documentation updates - all help is appreciated.

Areas that need attention:

More widget options and customization
Additional compositor compatibility
Performance optimizations
Documentation and examples

Credits

quickshell the core of what makes a shell like this possible.
niri for the awesome scrolling compositor.
soramanew who built caelestia which served as inspiration and guidance for many dank widgets.
end-4 for dots-hyprland which also served as inspiration and guidance for many dank widgets.

Languages

QML 58%

Go 32.3%

CSS 4.7%

Shell 1.8%

JavaScript 1.6%

Other 1.6%

README.md

DankMaterialShell