1waybar-custom(5)              File Formats Manual             waybar-custom(5)
2
3
4

NAME

6       waybar - custom module
7

DESCRIPTION

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

CONFIGURATION

13       Addressed by custom/<name>
14
15       exec:
16            typeof: string
17            The path to the script, which should be executed.
18
19       exec-if:
20            typeof: string
21            The path to a script, which determines if the script in exec
22       should be executed.
23            exec will be executed if the exit code of exec-if equals 0.
24
25       exec-on-event:
26            typeof: bool
27            default: true
28            If an event command is set (e.g. on-click or on-scroll-up) then
29       re-execute the script after executing the event command.
30
31       return-type:
32            typeof: string
33            See return-type
34
35       interval:
36            typeof: integer
37            The interval (in seconds) in which the information gets polled.
38            Use once if you want to execute the module only on startup.
39            You can update it manually with a signal. If no interval is de‐
40       fined, it is assumed that the out script loops it self.
41
42       restart-interval:
43            typeof: integer
44            The restart interval (in seconds).
45            Can't be used with the interval option, so only with continuous
46       scripts.
47            Once the script exit, it'll be re-executed after the restart-in‐
48       terval.
49
50       signal:
51            typeof: integer
52            The signal number used to update the module.
53            The number is valid between 1 and N, where SIGRTMIN+N = SIGRTMAX.
54
55       format:
56            typeof: string
57            default: {}
58            The format, how information should be displayed. On {} data gets
59       inserted.
60
61       format-icons:
62            typeof: array
63            Based on the set percentage, the corresponding icon gets selected.
64       The order is low to high.
65
66       rotate:
67            typeof: integer
68            Positive value to rotate the text label.
69
70       max-length:
71            typeof: integer
72            The maximum length in character the module should display.
73
74       min-length:
75            typeof: integer
76            The minimum length in characters the module should take up.
77
78       align:
79            typeof: float
80            The alignment of the text, where 0 is left-aligned and 1 is right-
81       aligned. If the module is rotated, it will follow the flow of the text.
82
83       on-click:
84            typeof: string
85            Command to execute when clicked on the module.
86
87       on-click-middle:
88            typeof: string
89            Command to execute when middle-clicked on the module using mouse‐
90       wheel.
91
92       on-click-right:
93            typeof: string
94            Command to execute when you right clicked on the module.
95
96       on-update:
97            typeof: string
98            Command to execute when the module is updated.
99
100       on-scroll-up:
101            typeof: string
102            Command to execute when scrolling up on the module.
103
104       on-scroll-down:
105            typeof: string
106            Command to execute when scrolling down on the module.
107
108       smooth-scrolling-threshold:
109            typeof: double
110            Threshold to be used when scrolling.
111
112       tooltip:
113            typeof: bool
114            default: true
115            Option to disable tooltip on hover.
116
117       escape:
118            typeof: bool
119            default: false
120            Option to enable escaping of script output.
121

RETURN-TYPE

123       When return-type is set to json, Waybar expects the exec-script  to
124       output its data in JSON format. This should look like this:
125
126           {"text": "$text", "tooltip": "$tooltip", "class": "$class", "percentage": $percentage }
127
128       The class parameter also accepts an array of strings.
129
130       If nothing or an invalid option is specified, Waybar expects i3blocks
131       style output. Values are newline separated. This should look like this:
132
133           $text\n$tooltip\n$class*
134
135       class is a CSS class, to apply different styles in style.css
136

FORMAT REPLACEMENTS

138       {}: Output of the script.
139
140       {percentage} Percentage which can be set via a json return-type.
141
142       {icon}: An icon from 'format-icons' according to percentage.
143

EXAMPLES

145   Spotify:
146           "custom/spotify": {
147                "format": " {}",
148                "max-length": 40,
149                "interval": 30, // Remove this if your script is endless and write in loop
150                "exec": "$HOME/.config/waybar/mediaplayer.sh 2> /dev/null", // Script in resources folder
151                "exec-if": "pgrep spotify",
152                "return-type": "json"
153           }
154
155   mpd:
156           "custom/mpd": {
157                "format": "♪ {}",
158                //"max-length": 15,
159                "interval": 10,
160                "exec": "mpc current",
161                "exec-if": "pgrep mpd",
162                "on-click": "mpc toggle",
163                "on-click-right": "sonata"
164           }
165
166   cmus:
167           "custom/cmus": {
168                "format": "♪ {}",
169                //"max-length": 15,
170                "interval": 10,
171                "exec": "cmus-remote -C "format_print '%a - %t'"", // artist - title
172                "exec-if": "pgrep cmus",
173                "on-click": "cmus-remote -u",                        //toggle pause
174                "escape": true                                       //handle markup entities
175           }
176
177   Pacman
178           "custom/pacman": {
179                "format": "{}  ",
180                "interval": "once",
181                "exec": "pacman_packages",
182                "on-click": "update-system",
183                "signal": 8
184           }
185
186   Alternate Pacman
187           "custom/pacman": {
188                "format": "{}  ",
189                "interval": 3600,                     // every hour
190                "exec": "checkupdates | wc -l",       // # of updates
191                "exec-if": "exit 0",                  // always run; consider advanced run conditions
192                "on-click": "termite -e 'sudo pacman -Syu'; pkill -SIGRTMIN+8 waybar", // update system
193                "signal": 8
194           }
195
196       You can use the signal and update the number of available packages with
197       pkill -RTMIN+8 waybar.
198

STYLE

200#custom-<name>
201#custom-<name>.<class>
202<class> can be set by the script. For more information see return-
203           type
204
205
206
207                                  2023-08-16                  waybar-custom(5)
Impressum