Skip to content
Sven edited this page Nov 16, 2024 · 100 revisions

The custom module displays either the output of a script or static text. To display static text, specify only the format field.

Config

Addressed by custom/<name>

option typeof default description
exec string
exec-if string The path to a script, which determines if the script in exec should be executed.
exec will be executed if the exit code of exec-if equals 0.
exec-on-event bool true If an event command is set (e.g. on-click or on-scroll-up) then re-execute the script. There are no guarantees that exec is executed after the on-* event commands finished. See https://github.com/Alexays/Waybar/pull/1784 for a possible patch.
hide-empty-text bool false (Post-0.10.3 option) Disables the module when output is empty, but format might contain additional static content.
return-type string See return-type
interval integer The interval (in seconds) in which the information gets polled.
Use once if you want to execute the module only on startup. You can update it manually with a signal. If no interval is defined, it is assumed that the out script loops it self.
restart-interval integer The restart interval (in seconds).
Can't be used with the interval option, so only with continuous scripts.
Once the script exit, it'll be re-executed after the restart-interval.
signal integer The signal number used to update the module. The number is valid between 1 and N, where SIGRTMIN+N = SIGRTMAX.
format string {} The format, how information should be displayed. On {} data gets inserted.
format-icons array/object/string If the type is an array, then based on the set percentage, the corresponding icon gets selected (low to high).
If the type is an object, then the icon will be selected according to alt string from the output.
If the type is a string, it will be pasted as is.
NOTE: Arrays can be nested into objects. Icons will be selected first according to alt then percentage.
rotate integer Positive value to rotate the text label.
max-length integer The maximum length in character the module should display.
on-click string Command to execute when clicked on the module.
on-click-middle string Command to execute when you middle clicked on the module using mousewheel.
on-click-right string Command to execute when you right clicked on the module.
on-scroll-up string Command to execute when scrolling up on the module.
on-scroll-down string Command to execute when scrolling down on the module.
smooth-scrolling-threshold double Threshold to be used when scrolling.
tooltip bool true Option to enable tooltip on hover.
tooltip-format string The format of the tooltip.
escape bool false Option to enable escaping of script output

Return-Type:

  • When return-type is set to json, Waybar expects the exec-script to output its data in JSON format. This should look like this: {"text": "$text", "alt": "$alt", "tooltip": "$tooltip", "class": "$class", "percentage": $percentage }. This means the output should also be on a single line. This can be achieved by piping the output of your script through jq --unbuffered --compact-output. The class parameter also accepts an array of strings.
  • If you want to have multiline tooltips, use \r in your script
    • If using PowerShell for scripting, use the standard newline operator "`n" in double quotes; \r and \n will not work.
  • If nothing or an invalid option is specified Waybar expects i3blocks style output, where values are newline separated. This should look like this: $text\n$tooltip\n$class

class is a CSS class, to apply different styles in style.css

Continuous script:

The exec script may be continuous (i.e. contain some kind of infinite loop). The display will be updated for each new line of data on stdout (following the chosen return-type).

The interval option does not work with continuous script (no need to call it several times… as it will continuously run). However you might want to set the restart-interval to start again the script if it stops after some time.

Be warned that some technologies use a buffer for their output. If your module displays nothing even if your script is working as expected, the output might be hold temporarily in a buffer. Look for the correct way to flush the output buffer for your language of choice.

For example, in ruby you can do the following thing:

loop do
  puts { text: 'My module text', class: 'class',  }.to_json
  $stdout.flush
  sleep 5
end

Format replacements:

string replacement
{} Output of the script.
{percentage} Percentage which can be set via a json return-type.
{icon} An icon from 'format-icons' according to percentage.

Tooltip Format

tooltip-format can receive any of the above format replacements.

If the output of the custom script specifies a value in the tooltip field, this is the default. Otherwise, it is {}.

Style

  • #custom-<name>
  • #custom-<name>.<class>
    • <class> can be set by the script. For more information see return-type

Troubleshooting

Self-looping module don't show up

If your module is self-looping, and it doesn't even show up in the bar, check that:

  1. Its configuration does not include an interval parameter
  2. Output to stdout is not buffered (see #2358)

Custom json class not displayed

If you have a json class in your custom script that is not displayed by styles.css, the json with more variables must be displayed first (see #3234)

Clone this wiki locally