DankMaterialShell

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

WIP

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
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";
   }
}

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.