1waybar-custom(5) File Formats Manual waybar-custom(5)
2
6 waybar - custom module
7
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
13 Addressed by custom/<name>
14 exec:
16 typeof: string
17 The path to the script, which should be executed.
18 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 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 return-type:
32 typeof: string
33 See return-type
34 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 or signal
40 is defined, it is assumed that the out script loops itself.
41 If a signal is defined then the script will run once on startup
42 and will only update with a signal.
43 restart-interval:
45 typeof: integer
46 The restart interval (in seconds).
47 Can't be used with the interval option, so only with continuous
48 scripts.
49 Once the script exits, it'll be re-executed after the restart-in‐
50 terval.
51 signal:
53 typeof: integer
54 The signal number used to update the module.
55 The number is valid between 1 and N, where SIGRTMIN+N = SIGRTMAX.
56 If no interval is defined then a signal will be the only way to
57 update the module.
58 format:
60 typeof: string
61 default: {}
62 The format, how information should be displayed. On {} data gets
63 inserted.
64 format-icons:
66 typeof: array
67 Based on the set percentage, the corresponding icon gets selected.
68 The order is low to high.
69 rotate:
71 typeof: integer
72 Positive value to rotate the text label.
73 max-length:
75 typeof: integer
76 The maximum length in character the module should display.
77 min-length:
79 typeof: integer
80 The minimum length in characters the module should accept.
81 align:
83 typeof: float
84 The alignment of the text, where 0 is left-aligned and 1 is right-
85 aligned. If the module is rotated, it will follow the flow of the text.
86 on-click:
88 typeof: string
89 Command to execute when clicked on the module.
90 on-click-middle:
92 typeof: string
93 Command to execute when middle-clicked on the module using mouse‐
94 wheel.
95 on-click-right:
97 typeof: string
98 Command to execute when you right-click on the module.
99 on-update:
101 typeof: string
102 Command to execute when the module is updated.
103 on-scroll-up:
105 typeof: string
106 Command to execute when scrolling up on the module.
107 on-scroll-down:
109 typeof: string
110 Command to execute when scrolling down on the module.
111 smooth-scrolling-threshold:
113 typeof: double
114 Threshold to be used when scrolling.
115 tooltip:
117 typeof: bool
118 default: true
119 Option to disable tooltip on hover.
120 escape:
122 typeof: bool
123 default: false
124 Option to enable escaping of script output.
125
127 When return-type is set to json, Waybar expects the exec-script to
128 output its data in JSON format. This should look like this:
129 {"text": "$text", "tooltip": "$tooltip", "class": "$class", "percentage": $percentage }
131 The class parameter also accepts an array of strings.
133 If nothing or an invalid option is specified, Waybar expects i3blocks
135 style output. Values are newline separated. This should look like this:
136 $text\n$tooltip\n$class*
138 class is a CSS class, to apply different styles in style.css
140
142 {}: Output of the script.
143 {percentage} Percentage which can be set via a json return type.
145 {icon}: An icon from 'format-icons' according to percentage.
147
149 Spotify:
150 "custom/spotify": {
151 "format": " {}",
152 "max-length": 40,
153 "interval": 30, // Remove this if your script is endless and write in loop
154 "exec": "$HOME/.config/waybar/mediaplayer.sh 2> /dev/null", // Script in resources folder
155 "exec-if": "pgrep spotify",
156 "return-type": "json"
157 }
158 mpd:
160 "custom/mpd": {
161 "format": "♪ {}",
162 //"max-length": 15,
163 "interval": 10,
164 "exec": "mpc current",
165 "exec-if": "pgrep mpd",
166 "on-click": "mpc toggle",
167 "on-click-right": "sonata"
168 }
169 cmus:
171 "custom/cmus": {
172 "format": "♪ {}",
173 //"max-length": 15,
174 "interval": 10,
175 "exec": "cmus-remote -C "format_print '%a - %t'"", // artist - title
176 "exec-if": "pgrep cmus",
177 "on-click": "cmus-remote -u", //toggle pause
178 "escape": true //handle markup entities
179 }
180 Pacman
182 "custom/pacman": {
183 "format": "{} ",
184 "interval": "once",
185 "exec": "pacman_packages",
186 "on-click": "update-system",
187 "signal": 8
188 }
189 Alternate Pacman
191 "custom/pacman": {
192 "format": "{} ",
193 "interval": 3600, // every hour
194 "exec": "checkupdates | wc -l", // # of updates
195 "exec-if": "exit 0", // always run; consider advanced run conditions
196 "on-click": "termite -e 'sudo pacman -Syu'; pkill -SIGRTMIN+8 waybar", // update system
197 "signal": 8
198 }
199 You can use the signal and update the number of available packages with
201 pkill -RTMIN+8 waybar.
202
204 • #custom-<name>
205 • #custom-<name>.<class>
206 • <class> can be set by the script. For more information see return-
207 type
208 2023-11-05 waybar-custom(5)