.\" Generated by scdoc 1.11.5 .\" Complete documentation for this program is not available as a GNU info page .ie \n(.g .ds Aq \(aq .el .ds Aq ' .nh .ad l .\" Begin generated content: .TH "waybar\-custom" "5" "2026\-08\-31" .SH NAME .PP waybar \- custom module .PP .SH DESCRIPTION .PP The \fBcustom\fR module displays either the output of a script or static text.\& To display static text, specify only the \fBformat\fR field.\& .PP .SH CONFIGURATION .PP Addressed by \fBcustom/\fR .PP \fBexec\fR: .br typeof: string .br The path to the script, which should be executed.\& .PP \fBexec\-if\fR: .br typeof: string .br The path to a script, which determines if the script in \fBexec\fR should be executed.\& .br \fBexec\fR will be executed if the exit code of \fBexec\-if\fR equals 0.\& .PP \fBhide\-empty\-text\fR: .br typeof: bool .br Disables the module when output is empty, but format might contain additional static content.\& .PP \fBexec\-on\-event\fR: .br typeof: bool .br default: true .br If an event command is set (e.\&g.\& \fBon\-click\fR or \fBon\-scroll\-up\fR) then re\-execute the script after executing the event command.\& .PP \fBreturn\-type\fR: .br typeof: string .br See \fBreturn\-type\fR .PP \fBinterval\fR: .br typeof: integer or float .br The interval (in seconds) in which the information gets polled.\& .br Minimum value is 0.\&001 (1ms).\& Values smaller than 1ms will be set to 1ms.\& .br Use \fBonce\fR if you want to execute the module only on startup.\& .br You can update it manually with a signal.\& If no \fBinterval\fR or \fBsignal\fR is defined, it is assumed that the out script loops itself.\& .br If a \fBsignal\fR is defined then the script will run once on startup and will only update with a signal.\& .PP \fBrestart\-interval\fR: .br typeof: integer or float .br The restart interval (in seconds).\& .br Minimum value is 0.\&001 (1ms).\& Values smaller than 1ms will be set to 1ms.\& .br Can'\&t be used with the \fBinterval\fR option, so only with continuous scripts.\& .br Once the script exits, it'\&ll be re\-executed after the \fBrestart\-interval\fR.\& .PP \fBsignal\fR: .br typeof: integer .br The signal number used to update the module.\& .br The number is valid between 1 and N, where \fBSIGRTMIN+N\fR = \fBSIGRTMAX\fR.\& .br If no interval is defined then a signal will be the only way to update the module.\& .PP \fBformat\fR: .br typeof: string .br default: {text} .br The format, how information should be displayed.\& On {text} data gets inserted.\& .PP \fBformat\-icons\fR: .br typeof: array .br Based on the set percentage, the corresponding icon gets selected.\& The order is \fBlow\fR to \fBhigh\fR.\& .PP \fBrotate\fR: .br typeof: integer .br Positive value to rotate the text label (in 90 degree increments).\& .PP \fBmax\-length\fR: .br typeof: integer .br The maximum length in character the module should display.\& .PP \fBmin\-length\fR: .br typeof: integer .br The minimum length in characters the module should accept.\& .PP \fBalign\fR: .br typeof: float .br The alignment of the label within the module, where 0 is left\-aligned and 1 is right\-aligned.\& If the module is rotated, it will follow the flow of the text.\& .PP \fBjustify\fR: .br typeof: string .br The alignment of the text within the module'\&s label, allowing options '\&left'\&, '\&right'\&, or '\¢er'\& to define the positioning.\& .PP \fBon\-click\fR: .br typeof: string .br Command to execute when clicked on the module.\& .PP \fBon\-click\-middle\fR: .br typeof: string .br Command to execute when middle\-clicked on the module using mousewheel.\& .PP \fBon\-click\-right\fR: .br typeof: string .br Command to execute when you right\-click on the module.\& .PP \fBon\-update\fR: .br typeof: string .br Command to execute when the module is updated.\& .PP \fBon\-scroll\-up\fR: .br typeof: string .br Command to execute when scrolling up on the module.\& .PP \fBon\-scroll\-down\fR: .br typeof: string .br Command to execute when scrolling down on the module.\& .PP \fBsmooth\-scrolling\-threshold\fR: .br typeof: double .br Threshold to be used when scrolling.\& .PP \fBtooltip\fR: .br typeof: bool .br default: true .br Option to disable tooltip on hover.\& .PP \fBtooltip\-format\fR: .br typeof: string .br The tooltip format.\& If specified, overrides any tooltip output from the script in \fBexec\fR.\& .br Uses the same format replacements as \fBformat\fR.\& .PP \fBescape\fR: .br typeof: bool .br default: false .br Option to enable escaping of script output.\& .PP \fBmenu\fR: .br typeof: string .br Action that popups the menu.\& .PP \fBmenu\-file\fR: .br typeof: string .br Location of the menu descriptor file.\& There need to be an element of type .RS 4 GtkMenu with id \fBmenu\fR .PP .RE \fBmenu\-actions\fR: .br typeof: array .br The actions corresponding to the buttons of the menu.\& .PP \fBexpand\fR: .br typeof: bool .br default: false .br Enables this module to consume all left over space dynamically.\& .PP .SH RETURN\-TYPE .PP When \fBreturn\-type\fR is set to \fBjson\fR, Waybar expects the \fBexec\fR\-script to output its data in JSON format.\& This should look like this: .PP .nf .RS 4 {"text": "$text", "tooltip": "$tooltip", "class": "$class", "percentage": $percentage } .fi .RE .PP The \fBclass\fR parameter also accepts an array of strings.\& .PP If nothing or an invalid option is specified, Waybar expects i3blocks style output.\& Values are \fBnewline\fR separated.\& This should look like this: .PP .nf .RS 4 $text\\n$tooltip\\n$class* .fi .RE .PP \fBclass\fR is a CSS class, to apply different styles in \fBstyle.\&css\fR .PP .SH FORMAT REPLACEMENTS .PP \fB{text}\fR: Output of the script.\& .PP \fB{percentage}\fR Percentage which can be set via a json return type.\& .PP \fB{icon}\fR: An icon from '\&format\-icons'\& according to percentage.\& .PP .SH EXAMPLES .PP .SS Spotify: .PP .nf .RS 4 "custom/spotify": { "format": " {text}", "max\-length": 40, "interval": 30, // Remove this if your script is endless and write in loop "exec": "$HOME/\&.config/waybar/mediaplayer\&.sh 2> /dev/null", // Script in resources folder "exec\-if": "pgrep spotify", "return\-type": "json" } .fi .RE .PP .SS mpd: .PP .nf .RS 4 "custom/mpd": { "format": "♪ {text}", //"max\-length": 15, "interval": 10, "exec": "mpc current", "exec\-if": "pgrep mpd", "on\-click": "mpc toggle", "on\-click\-right": "sonata" } .fi .RE .PP .SS cmus: .PP .nf .RS 4 "custom/cmus": { "format": "♪ {text}", //"max\-length": 15, "interval": 10, "exec": "cmus\-remote \-C "format_print \&'%a \- %t\&'"", // artist \- title "exec\-if": "pgrep cmus", "on\-click": "cmus\-remote \-u", //toggle pause "escape": true //handle markup entities } .fi .RE .PP .SS Pacman .PP .nf .RS 4 "custom/pacman": { "format": "{text} ", "interval": "once", "exec": "pacman_packages", "on\-click": "update\-system", "signal": 8 } .fi .RE .PP .SS Alternate Pacman .PP .nf .RS 4 "custom/pacman": { "format": "{text} ", "exec": "checkupdates | wc \-l", // # of updates "exec\-if": "exit 0", // always run; consider advanced run conditions "on\-click": "termite \-e \&'sudo pacman \-Syu\&'; pkill \-SIGRTMIN+8 waybar", // update system "signal": 8 } .fi .RE .PP Under the premise that interval is not defined, you can use the signal and update the number of available packages with \fBpkill \-RTMIN+8 waybar\fR.\& .PP .SH STYLE .PP .PD 0 .IP \(bu 4 \fB#custom\-\fR .IP \(bu 4 \fB#custom\-.\&\fR .IP \(bu 4 \fB\fR can be set by the script.\& For more information see \fBreturn\-type\fR