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
30           executing the event command.
31
32       return-type:
33            typeof: string
34            See return-type
35
36       interval:
37            typeof: integer
38            The interval (in seconds) in which the information gets polled.
39           Use once if you want to execute the module only on startup. You can
40           update it manually with a signal. If no interval is defined, it is
41           assumed that the out script loops it self.
42
43       restart-interval:
44            typeof: integer
45            The restart interval (in seconds).
46           Can't be used with the interval option, so only with continuous
47           scripts. Once the script exit, it'll be re-executed after the
48           restart-interval.
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           }
153
154   mpd:
155           "custom/mpd": {
156                "format": "♪ {}",
157                //"max-length": 15,
158                "interval": 10,
159                "exec": "mpc current",
160                "exec-if": "pgrep mpd",
161                "on-click": "mpc toggle",
162                "on-click-right": "sonata"
163           }
164
165   cmus:
166           "custom/cmus": {
167                "format": "♪ {}",
168                //"max-length": 15,
169                "interval": 10,
170                "exec": "cmus-remote -C "format_print '%a - %t'"", // artist - title
171                "exec-if": "pgrep cmus",
172                "on-click": "cmus-remote -u",                        //toggle pause
173                "escape": true                                       //handle markup entities
174           }
175
176   Pacman
177           "custom/pacman": {
178                "format": "{}  ",
179                "interval": "once",
180                "exec": "pacman_packages",
181                "on-click": "update-system",
182                "signal": 8
183           }
184
185   Alternate Pacman
186           "custom/pacman": {
187                "format": "{}  ",
188                "interval": 3600,                     // every hour
189                "exec": "checkupdates | wc -l",       // # of updates
190                "exec-if": "exit 0",                  // always run; consider advanced run conditions
191                "on-click": "termite -e 'sudo pacman -Syu'; pkill -SIGRTMIN+8 waybar", // update system
192                "signal": 8
193           }
194
195       You can use the signal and update the number of available packages with
196       pkill -RTMIN+8 waybar.
197

STYLE

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