Skip to main content

Custom Modules

This special module type lets you extend the functionality of Ashell by creating your own simple components.

A custom module allows you to:

  • Display the output of a command (live).
  • Run a command when the module is clicked.
  • Change icons dynamically based on output.
  • Show an alert indicator based on specific conditions.

Configuration​

To define a custom module, use the following fields:

  • name: Name of the module. Use this to refer to it in the modules definitions.
  • icon: Icon displayed in the status bar.
  • command: Command to execute when the module is clicked.
  • listen_cmd (optional): Command to run in the background to update the module’s display.
  • icons (optional): Regex-to-icon mapping to change the icon based on the listen_cmd output.
  • alert (optional): Regex to trigger a red alert dot on the icon when matched in the listen_cmd output.

listen_cmd​

The listen_cmd should output JSON in the Waybar format, using text and alt fields.

Example Output​

{
  "text": "3",
  "alt": "notification"
}

Dynamic Icons​

You can change the icon depending on the value of alt in the listen_cmd output.

Icons Example​

icons.'dnd.*' = "ο‡·"

This will change the icon to ο‡· when alt matches dnd.*.

Alerts​

Use the alert field to show a red dot on the module icon if the output matches a given regex.

Alerts Example​

alert = ".*notification"

Examples​

Notifications (with swaync-client)​

[[CustomModule]]
name = "CustomNotifications"
icon = "ο‚’"
command = "swaync-client -t -sw"
listen_cmd = "swaync-client -swb"
icons.'dnd.*' = "ο‡·"
alert = ".*notification"

App Launcher (with walker)​

[[CustomModule]]
name = "AppLauncher"
icon = "σ±—Ό"
command = "walker"