Skip to main content
Version: 1.6

Overview

██████╗ ██╗     ██╗   ██╗ ██████╗ ██╗███╗   ██╗███████╗
██╔══██╗██║     ██║   ██║██╔════╝ ██║████╗  ██║██╔════╝
██████╔╝██║     ██║   ██║██║  ███╗██║██╔██╗ ██║███████╗
██╔═══╝ ██║     ██║   ██║██║   ██║██║██║╚██╗██║╚════██║
██║     ███████╗╚██████╔╝╚██████╔╝██║██║ ╚████║███████║
╚═╝     ╚══════╝ ╚═════╝  ╚═════╝ ╚═╝╚═╝  ╚═══╝╚══════╝

DankMaterialShell's plugin system allows extending the desktop with custom widgets, launchers, automation, and integrations through QML components.

Plugin Location​

Plugins are installed to ~/.config/DankMaterialShell/plugins/. Each plugin is a directory containing a plugin.json manifest and QML components.

Official plugins: github.com/AvengeMedia/dms-plugins Plugin registry: plugins.danklinux.com Registry source: github.com/AvengeMedia/dms-plugin-registry Example plugins: github.com/AvengeMedia/DankMaterialShell/tree/master/quickshell/PLUGINS

The plugin directory ranks plugins by community 👍 upvotes. Each plugin has a tracking issue in the registry you can upvote and discuss — see Contributing to the Registry.

Plugin Types​

DankMaterialShell supports the following plugin types, defined in plugin.json:

1. Bar Widget (type: "widget")​

Widgets that appear in DankBar. Define horizontalBarPill and verticalBarPill components for different bar orientations.

Capabilities:

  • dankbar-widget - Appears in DankBar

Example use cases: System monitors, media controls, weather widgets, clock displays

2. Control Center Widget (type: "widget")​

Widgets that appear in the Control Center quick settings panel. Define ccWidget* properties for toggle buttons and detail panels.

Capabilities:

  • control-center - Appears in Control Center

Example use cases: VPN toggles, custom shortcuts, service controls

3. Launcher Plugin (type: "launcher")​

Extends the application launcher with custom searchable items. Define getItems() and executeItem() functions.

Capabilities:

  • launcher - Adds items to Spotlight search

Required fields:

  • trigger - Trigger string for filtering (e.g., "#", "!", "" for always-visible)

Example use cases: Emoji picker, calculator, web search, custom actions

4. Daemon (type: "daemon")​

Background services with no UI. Run automation, monitoring, or provide services to other plugins.

Capabilities:

  • daemon - Background service
  • watch-events - React to system events

Example use cases: Battery alerts, wallpaper automation, notification handlers

5. Desktop Widget (type: "desktop")​

Widgets that render directly on the desktop background layer using Wayland's wlr-layer-shell protocol. Users can drag them anywhere and resize via corner handles.

Capabilities:

  • desktop-widget - Appears on the desktop layer

Features:

  • Free positioning anywhere on desktop
  • Resizing with minimum size constraints
  • Multi-monitor support with independent positions per screen
  • Position/size persistence across sessions

Example use cases: Desktop clock, system monitor, weather widget, sticky notes

6. Composite Plugin (type: "composite")​

A single plugin that provides several of the above surfaces at once — for example a daemon plus a bar widget plus a desktop widget. Instead of one component, it declares a components map pointing each surface at its own QML file.

Features:

  • Any combination of widget, desktop, daemon, and launcher surfaces
  • One settings UI and one settings namespace shared across all surfaces
  • Shared runtime state via plugin global variables or the daemon instance

Example use cases: A monitor daemon that also shows a bar pill and a desktop tile; an integration that exposes both a launcher and a background watcher

Composite plugins require DMS ≥ 1.5.0. See the development guide for details.

Installation​

From GitHub​

mkdir -p ~/.config/DankMaterialShell/plugins
cd ~/.config/DankMaterialShell/plugins
git clone https://github.com/author/plugin-name
dms restart

From Plugin Registry​

Browse plugins.danklinux.com for installation links and documentation.

Reproduce Managed Plugins​

DMS keeps ~/.config/DankMaterialShell/plugins.lock.json synchronized when registry plugins are installed, updated, or removed. The lockfile records each Git repository, optional monorepo path, and exact commit.

# Refresh the lockfile and optionally export a copy
dms plugins lock
dms plugins lock --output ~/plugins.lock.json

# Install or reset plugins to the exact locked commits
dms plugins restore ~/plugins.lock.json

# Also remove managed plugins that are absent from the lockfile
dms plugins restore ~/plugins.lock.json --prune

The lockfile covers DMS-managed Git plugins. It does not include system plugins, plugin settings, enablement state, or local plugin directories without Git provenance.

Enable Plugin​

  1. Open Settings → Plugins
  2. Click Scan for Plugins
  3. Toggle the plugin on
  4. Add to DankBar layout if applicable
  5. Restart shell: dms restart

Custom Registries​

DMS fetches installable plugins and themes from registries — Git repositories containing plugins/ and/or themes/ directories in the registry format. The official registry is always active; additional registries can be added alongside it.

Requires DMS ≥ 1.6.0.

Managing Registries​

GUI: Settings → Plugins → Registries — add a registry by name and Git URL, or remove one. The official registry cannot be removed.

CLI:

# Show configured registries
dms registry list

# Add a registry by name and Git URL
dms registry add myregistry https://github.com/user/my-registry.git

# Remove a registry
dms registry remove myregistry

Additional registries are stored in ~/.config/DankMaterialShell/registries.json. Names are short lowercase identifiers (letters, digits, hyphens) and become the local cache directory for that registry.

Resolution Order​

Registries are consulted in declaration order, official first. When two registries provide the same plugin or theme ID, the first occurrence wins — a custom registry cannot override an official entry. An unreachable registry is skipped so the remaining registries keep working.

Registry Format​

A registry is a Git repository with either or both of:

  • plugins/*.json — one plugin manifest per file
  • themes/<theme-id>/theme.json — one directory per theme

A registry can provide only plugins, only themes, or both. See dms-plugin-registry for the manifest schema.

Plugins run with full desktop session permissions. Only add registries you trust.

Official Plugins​

Maintained by the DankMaterialShell team at dms-plugins:

  • Dank Actions - Scriptable bar buttons and control center tiles
  • Dank Hooks - Event-based automation triggers
  • Dank Pomodoro Timer - Focus timer with notifications
  • Dank Battery Alerts - Battery threshold warnings

Community Plugins​

Third-party plugins submitted to the registry at plugins.danklinux.com:

  • WallpaperShuffler - Automatic wallpaper rotation
  • WorldClock - Multi-timezone clock widget
  • PowerUsage - Real-time power consumption monitor
  • Calculator - Launcher-based calculator

Always review plugin source code before installation. Plugins run with full desktop session permissions.

Development​

See Plugin Development for the complete development guide including:

  • Plugin manifest structure (plugin.json)
  • Component architecture
  • PluginService API
  • Settings components
  • Bar and Control Center integration
  • Launcher plugin development
  • Global variables and state management
  • Plugin translations (translations/ + I18n.trFor)

Translations​

Plugins carry their own translations — a translations/ directory in the plugin repo with one JSON file per locale. DMS picks the file matching your locale automatically and updates live when you switch languages in Settings → Locale. Nothing to configure as a user; if the plugin ships your language, you get it.

For plugin authors: see Translations in the development guide for the file format and the I18n.trFor API. Registry plugins can also apply for central translation through the same POEditor project that translates DMS itself.

Example Plugins​

Reference implementations in the main repository:

Plugin Registry Submission​

To add your plugin to the registry:

  1. Create a public GitHub repository
  2. Include plugin.json, README, and screenshots
  3. Validate manifest against plugin-schema.json
  4. Submit PR to dms-plugin-registry
  5. Site rebuilds automatically on merge

Troubleshooting​

Plugin not detected:

  • Verify plugin.json syntax with jq .
  • Check directory is in ~/.config/DankMaterialShell/plugins/
  • Click "Scan for Plugins" in Settings

Plugin won't load:

  • Check logs: dms kill && dms run from terminal
  • Verify component paths in plugin.json
  • Ensure dependencies are installed

Settings not working:

  • Add "permissions": ["settings_write"] to manifest
  • Use PluginSettings wrapper component
  • Check PluginService is injected properly

Next Steps​