DankMaterialShell (dms)

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

Screenshots

screencastsmol.mp4

View More Screenshots

Desktop Overview

Dashboard

Application Launcher

Control Center

System Monitor

Widget Customization

Lock Screen

Dynamic Theming

Notification Center

Dock

Quick start (full dotfiles, most distros)

curl -fsSL https://install.danklinux.com | sh

Or skip to Installation

Features

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 Configurable workspace switcher.
  • Focused Window Displays the currently focused window app name and title.
  • Running Apps A view of all running apps, sorted by monitor, workspace, then position on workspace.
  • 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, and GPU usage percentages, temperatures. (requires dgop)
  • 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
  • Privacy Indicator Attempts to reveal if a microphone or screen recording session is active, relying on Pipewire data sources
  • Idle Inhibitor Creates a systemd idle inhibitor to prevent sleep/locking from occuring.
• 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, display controls, and night mode automation.
• Lock Screen Using quickshell's WlSessionLock with embedded virtual keyboard for Niri (Niri doesn't support placing virtual keyboard above lockscreen natively: issue)
• Notepad A simple text notepad/scratchpad with auto-save to session data and file export/import functionality.

Highlights

• Auto-theming GTK, QT, Terminal apps, and more with matugen + optional theme generation from wallpaper.
• 20+ widgets that can be added and re-arranged on the bar.
• Process list, temperature monitoring, and resource monitoring with dgop
• Notification service with support for grouping and richtext
• App launcher + Spotlighht launcher with fuzzy search
• Control center with mpris player, weather, and calendar integration.
• Clipboard history view with image previews.
• A dock for running apps + pinned apps
• Configure bluetooth, wifi, and audio input+output devices.
• A lock screen
• Idle monitoring - configure auto lock, screen off, suspend, and hibernate with different knobs for battery + AC power.

TL;DR dms replaces your waybar, swaylock, swayidle, hypridle, hyprlock, fuzzels, walker, mako, and basically everything you use to stitch a desktop together

Installation

Compositor Setup

DankMaterialShell supports both niri and Hyprland compositors:

Niri:

# Arch Linux
paru -S niri-git

# Fedora  
sudo dnf copr enable yalter/niri && sudo dnf install niri

For detailed niri installation instructions, see the niri Getting Started guide.

Hyprland:

# Arch Linux
sudo pacman -S hyprland

# Or from AUR for latest
paru -S hyprland-git

# Fedora
sudo dnf install hyprland

# Or use Copr for latest builds
sudo dnf copr enable solopasha/hyprland && sudo dnf install hyprland

For detailed Hyprland installation instructions, see the Hyprland wiki.

Dank Shell Installation

feel free to contribute steps for other distributions

Arch Linux - via AUR

paru -S dms-shell-git

nixOS - via flake

nix profile install github:AvengeMedia/DankMaterialShell

nixOS - via home-manager

To install using home-manager, you need to add this repo into your flake inputs:

dankMaterialShell = {
  url = "github:AvengeMedia/DankMaterialShell";
  inputs.nixpkgs.follows = "nixpkgs";
};

Then somewhere in your home-manager config, add this to the imports:

imports = [
  inputs.dankMaterialShell.homeModules.dankMaterialShell.default
];

If you use Niri, the niri homeModule provides additional options for Niri integration, such as key bindings and spawn:

imports = [
  inputs.dankMaterialShell.homeModules.dankMaterialShell.default
  inputs.dankMaterialShell.homeModules.dankMaterialShell.niri
];

Important

To use the niri homeModule, you must have sobidoo/niri-flake in your inputs:

niri = {
  url = "github:sodiboo/niri-flake";
  inputs.nixpkgs.follows = "nixpkgs";
};

And import it in home-manager:

imports = [
  inputs.niri.homeModules.niri
];

Now you can enable it with:

programs.dankMaterialShell.enable = true;

There are a lot of possible configurations that you can enable/disable in the flake, check nix/default.nix and nix/niri.nix to see them all.

Other Distributions - via manual installation

1. Install Quickshell (Varies by Distribution)

# Arch
paru -S quickshell-git
# Fedora
sudo dnf copr enable errornointernet/quickshell && sudo dnf install quickshell-git
# ! TODO - document other distros

2. Install fonts Inter Variable and Fira Code are not strictly required, but they are the default fonts of dms.

2.1 Install Material Symbols

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

2.2 Install Inter Variable

curl -L "https://github.com/rsms/inter/raw/refs/tags/v4.1/docs/font-files/InterVariable.ttf" -o ~/.local/share/fonts/InterVariable.ttf

2.3 Install Fira Code (monospace font)

curl -L "https://github.com/tonsky/FiraCode/releases/latest/download/FiraCode-Regular.ttf" -o ~/.local/share/fonts/FiraCode-Regular.ttf

2.4 Refresh font cache

fc-cache -fv

3. Install the shell

3.1. Clone latest master

mkdir ~/.config/quickshell && git clone https://github.com/AvengeMedia/DankMaterialShell.git ~/.config/quickshell/dms

3.2. Install latest dms CLI

sudo sh -c "curl -L https://github.com/AvengeMedia/danklinux/releases/latest/download/dms-$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').gz | gunzip | tee /usr/local/bin/dms > /dev/null && chmod +x /usr/local/bin/dms"

4. Optional Features (system monitoring, clipboard history, brightness controls, etc.)

4.1 Core optional dependencies

# Arch Linux
sudo pacman -S cava wl-clipboard cliphist brightnessctl
paru -S matugen-bin dgop

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

Other distros will just need to find sources for the above packages

4.2 - dgop manual installation

dgop is available via AUR and a nix flake, other distributions can install it manually.

sudo sh -c "curl -L https://github.com/AvengeMedia/dgop/releases/latest/download/dgop-linux-$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').gz | gunzip | tee /usr/local/bin/dgop > /dev/null && chmod +x /usr/local/bin/dgop"

Optional Requirement Overview

• dgop: Ability to have system resource widgets, process list modal, and temperature monitoring.
• matugen: Wallpaper-based dynamic theming
• brightnessctl: Backlight and LED brightness control
• wl-clipboard: Required for copying various elements to clipboard.
• cava: Audio visualizer
• cliphist: Clipboard history
• gammastep: Night mode support

Compositor Configuration

A lot of options are subject to personal preference, but the below sets a good starting point for most features.

Niri Integration

Add to your niri config

// Required for clipboard history integration
spawn-at-startup "bash" "-c" "wl-paste --watch cliphist store &"

// Recommended (must install polkit-mate before hand) for elevation prompts
spawn-at-startup "/usr/lib/mate-polkit/polkit-mate-authentication-agent-1"
// This may be a different path on different distributions, the above is for the arch linux mate-polkit package

// Starts DankShell
spawn-at-startup "dms" "run"

// If using niri newer than 271534e115e5915231c99df287bbfe396185924d (~aug 17 2025)
// you can add this to disable built in config load errors since dank shell provides this
config-notification {
    disable-failed
}

// 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 "dms" "ipc" "call" "spotlight" "toggle";
   }
   Mod+V hotkey-overlay-title="Clipboard Manager" {
      spawn "dms" "ipc" "call" "clipboard" "toggle";
   }
   Mod+M hotkey-overlay-title="Task Manager" {
      spawn "dms" "ipc" "call" "processlist" "toggle";
   }
   Mod+N hotkey-overlay-title="Notification Center" {
      spawn "dms" "ipc" "call" "notifications" "toggle";
   }
   Mod+Comma hotkey-overlay-title="Settings" {
      spawn "dms" "ipc" "call" "settings" "toggle";
   }
   Mod+P hotkey-overlay-title="Notepad" {
      spawn "dms" "ipc" "call" "notepad" "toggle";
   }
   Super+Alt+L hotkey-overlay-title="Lock Screen" {
      spawn "dms" "ipc" "call" "lock" "lock";
   }
   Mod+X hotkey-overlay-title="Power Menu" {
      spawn "dms" "ipc" "call" "powermenu" "toggle";
   }
   Mod+C hotkey-overlay-title="Control Center" {
      spawn "dms" "ipc" "call" "control-center" "toggle";
   }
   XF86AudioRaiseVolume allow-when-locked=true {
      spawn "dms" "ipc" "call" "audio" "increment" "3";
   }
   XF86AudioLowerVolume allow-when-locked=true {
      spawn "dms" "ipc" "call" "audio" "decrement" "3";
   }
   XF86AudioMute allow-when-locked=true {
      spawn "dms" "ipc" "call" "audio" "mute";
   }
   XF86AudioMicMute allow-when-locked=true {
      spawn "dms" "ipc" "call" "audio" "micmute";
   }
   XF86MonBrightnessUp allow-when-locked=true {
      spawn "dms" "ipc" "call" "brightness" "increment" "5" "";
   }
   // You can override the default device for e.g. keyboards by adding the device name to the last param
   XF86MonBrightnessDown allow-when-locked=true {
      spawn "dms" "ipc" "call" "brightness" "decrement" "5" "";
   }
   // Night mode toggle
   Mod+Shift+N allow-when-locked=true {
      spawn "dms" "ipc" "call" "night" "toggle";
   }
}

Hyprland Integration

Add to your Hyprland config (~/.config/hypr/hyprland.conf):

# Required for clipboard history integration
exec-once = bash -c "wl-paste --watch cliphist store &"

# Recommended (must install polkit-mate beforehand) for elevation prompts  
exec-once = /usr/lib/mate-polkit/polkit-mate-authentication-agent-1
# This may be a different path on different distributions, the above is for the arch linux mate-polkit package

# Starts DankShell
exec-once = dms run

# 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

# Application and system controls
bind = SUPER, Space, exec, dms ipc call spotlight toggle
bind = SUPER, V, exec, dms ipc call clipboard toggle
bind = SUPER, M, exec, dms ipc call processlist toggle
bind = SUPER, N, exec, dms ipc call notifications toggle
bind = SUPER, comma, exec, dms ipc call settings toggle
bind = SUPER, P, exec, dms ipc call notepad toggle
bind = SUPERALT, L, exec, dms ipc call lock lock
bind = SUPER, X, exec, dms ipc call powermenu toggle
bind = SUPER, C, exec, dms ipc call control-center toggle 

# Audio controls (function keys)
bindl = , XF86AudioRaiseVolume, exec, dms ipc call audio increment 3
bindl = , XF86AudioLowerVolume, exec, dms ipc call audio decrement 3
bindl = , XF86AudioMute, exec, dms ipc call audio mute
bindl = , XF86AudioMicMute, exec, dms ipc call audio micmute

# Brightness controls (function keys)
bindl = , XF86MonBrightnessUp, exec, dms ipc call brightness increment 5 ""
# You can override the default device for e.g. keyboards by adding the device name to the last param
bindl = , XF86MonBrightnessDown, exec, dms ipc call brightness decrement 5 ""

# Night mode toggle
bind = SUPERSHIFT, N, exec, dms ipc call night toggle

IPC Commands

Control everything from the command line, or via keybinds. For comprehensive documentation of all available IPC commands, see docs/IPC.md.

Audio control

dms ipc call audio setvolume 50
dms ipc call audio mute

Launch applications

dms ipc call spotlight toggle
dms ipc call notepad toggle
dms ipc call processlist toggle
dms ipc call powermenu toggle

System control

dms ipc call wallpaper set /path/to/image.jpg
dms ipc call theme toggle
dms ipc call night toggle
dms ipc call lock lock

Media control

dms ipc call mpris playPause
dms ipc call mpris next

Theming

dms will spawn a matugen process on theme changes to generate color palettes for installed and supported apps. If you do not want these files generated, you can set the env variable DMS_DISABLE_MATUGEN=1 to disable it entirely.

Custom Themes

DankMaterialShell supports custom color themes! You can create your own Material Design 3 color schemes or use pre-made themes like Cyberpunk Electric, Hotline Miami, and Miami Vice.

For detailed instructions on creating and using custom themes, see docs/CUSTOM_THEMES.md.

System App Integration

There's two toggles in the appearance section of settings, for GTK and QT apps.

These settings will override some local GTK and QT configuration files, you can still integrate auto-theming if you do not wish DankShell to mess with your QTCT/GTK files.

No matter what when matugen is enabled the files will be created on wallpaper changes:

• ~/.config/gtk-3.0/dank-colors.css
• ~/.config/gtk-4.0/dank-colors.css
• ~/.config/qt6ct/colors/matugen.conf
• ~/.config/qt5ct/colors/matugen.conf

If you do not like our theme path, you can integrate this with other GTK themes, matugen themes, etc.

GTK Apps

1. Install Colloid

Colloid is a hard requirement for the auto-theming because of how it integrates with colloid css files, however you can integrate auto-theming with other themes, you just have to do it manually (so leave the toggle OFF in settings)

It will still create ~/.config/gtk-3.0/4.0/dank-colors.css on theme updates, these you can import into other compatible GTK themes.

# Some default install settings for colloid
./install.sh -s standard -l --tweaks normal

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

[Settings]
gtk-theme-name=Colloid

QT: basic gtk3 based theme (Option 1)

If you mostly use gtk apps, you'll probably be happy to just set the QT platform theme to gtk3.

environment {
  // Add to existing environment block
  QT_QPA_PLATFORMTHEME "gtk3"
  QT_QPA_PLATFORMTHEME_QT6 "gtk3"
}

QT: better theming (Option 2)

1. Install qt6ct-kde

# Arch
paru -S qt6ct-kde

*I'm not sure what it is on other distros, but you can manually install via instructions provides on qt6ct-kde github

2. Configure Environment in niri

  // Add to existing environment block
  QT_QPA_PLATFORMTHEME "qt6ct"
  QT_QPA_PLATFORMTHEME_QT6 "qt6ct"

You'll have to restart your session for themes to take effect.

Nevigate to dms settings -> themes & colors -> and click "Apply QT Themes"

Firefox

There are two theme paths for Firefox, using with pywalfox or material fox

(Option 1) - pywalfox

1. Install pywalfox on system.

• Available in AUR via paru -S python-pywalfox

2. Install pywalfox extension in firefox.

3. Restart dms and create symlink to generate palette and then enable dank colors.

• Run ln -sf ~/.cache/wal/dank-pywalfox.json ~/.cache/wal/colors.json

(Option 2) - Chrome-like theme with dynamic colors

Firefox does use the GTK3 theme, but it doesn't look that good on the stock theme IMO. A separate matugen css is generated for the material fox theme, you can configure that theme with dynamic colors by following the steps below.

1. In firefox, navigate to about:config

• set toolkit.legacyuserprofilecustomizations.stylesheets to true
• set svg.context-properties.content.enabled to true
• Create a new property called userChrome.theme-material and type boolean
  • set to true

Expand for firefox screenshots

2. Install material fox theme

# Find Firefox profile directory
export PROFILE_DIR=$(find ~/.mozilla/firefox -maxdepth 1 -type d -name "*.default-release" | head -n 1)

# Download, extract to profile dir, and cleanup
curl -L -o "$PROFILE_DIR/chrome.zip" https://github.com/edelvarden/material-fox-updated/releases/download/v2.0.0/chrome.zip
unzip -o "$PROFILE_DIR/chrome.zip" -d "$PROFILE_DIR"
rm "$PROFILE_DIR/chrome.zip"

3. Configure dynamic colors for material fox theme

export PROFILE_DIR=$(find ~/.mozilla/firefox -maxdepth 1 -type d -name "*.default-release" | head -n 1)
rm -f "$PROFILE_DIR/chrome/theme-material-blue.css"
ln -sf ~/.config/DankMaterialShell/firefox.css "$PROFILE_DIR/chrome/theme-material-blue.css"

Terminal Integration

The matugen integration will automatically generate new colors for certain apps only if they are installed.

You can enable the dynamic color schemes in supported terminal apps by modifying their configurations:

Ghostty:

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

If you want to disable excessive config reloaded popup sin ghostty, you may wish to also add this:

# These are the default danklinux options, if you still want config reloaded and copied to clipboard popups you can skip it.
echo "app-notifications = no-clipboard-copy,no-config-reload" >> ~/.config/ghostty/config

kitty:

echo "include dank-theme.conf" >> ~/.config/kitty/kitty.conf

Calendar Setup

Sync your caldev compatible calendar (Google, Office365, etc.) for dashboard integration:

Configuration Steps

Install dependencies:

Arch

sudo 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
• Re-run the shell with dms kill && dms run to capture logs.
• 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.
• Ly-sec for awesome wallpaper effects among other things from Noctalia
• 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.