1waybar(5) File Formats Manual waybar(5)
2
6 waybar - configuration file
7
9 The configuration uses the JSON file format and is named config.
10 Valid locations for this file are:
12 • $XDG_CONFIG_HOME/waybar/config
14 • ~/.config/waybar/config
15 • ~/waybar/config
16 • /etc/xdg/waybar/config
17 • /etc/xdg/waybar/config
18 A good starting point is the default configuration found at
21 https://github.com/Alexays/Waybar/blob/master/resources/config Also, a
22 minimal example configuration can be found at the bottom of this man
23 page.
24
26 layer
27 typeof: string
28 default: bottom
29 Decide if the bar is displayed in front (top) of the windows or
30 behind (bottom)
31 them.
32 output
34 typeof: string|array
35 Specifies on which screen this bar will be displayed. Exclamation
36 mark(!) can be used to exclude specific output.
37 Output specification follows sway's and can either be the output
38 port such as "HDMI-A-1" or a string consisting of the make, model,
39 and serial such as "Some Company ABC123 0x00000000". See sway-out‐
40 put(5) for details. In an array, star '*' can be used at the end to
41 accept all outputs, in case all previous entries are exclusions.
42 position
44 typeof: string
45 default: top
46 Bar position, can be top, bottom, left, right.
47 height
49 typeof: integer
50 Height to be used by the bar if possible. Leave blank for a dy‐
51 namic value.
52 width
54 typeof: integer
55 Width to be used by the bar if possible. Leave blank for a dynamic
56 value.
57 modules-left
59 typeof: array
60 Modules that will be displayed on the left.
61 modules-center
63 typeof: array
64 Modules that will be displayed in the center.
65 modules-right
67 typeof: array
68 Modules that will be displayed on the right.
69 margin
71 typeof: string
72 Margins value using the CSS format without units.
73 margin-<top|left|bottom|right>
75 typeof: integer
76 Margins value without units.
77 spacing
79 typeof: integer
80 Size of gaps in between the different modules.
81 name
83 typeof: string
84 Optional name added as a CSS class, for styling multiple waybars.
85 mode
87 typeof: string
88 Selects one of the preconfigured display modes. This is an equiva‐
89 lent of the sway-bar(5) mode command and supports the same values:
90 dock, hide, invisible, overlay.
91 Note: hide and invisible modes may be not as useful without Sway
92 IPC.
93 start_hidden
95 typeof: bool
96 default: false
97 Option to start the bar hidden.
98 modifier-reset
100 typeof: string
101 default: press
102 Defines the timing of modifier key to reset the bar visibility. To
103 reset the visibility of the bar with the press of the modifier key
104 use press. Use release to reset the visibility upon the release of
105 the modifier key and only if no other action happened while the key
106 was pressed. This prevents hiding the bar when the modifier is used
107 to switch a workspace, change binding mode, or start a keybinding.
108 exclusive
110 typeof: bool
111 default: true
112 Option to request an exclusive zone from the compositor. Disable
113 this to allow drawing application windows underneath or on top of the
114 bar.
115 fixed-center
117 typeof: bool
118 default: true
119 Prefer fixed center position for the `modules-center` block. The
120 center block will stay in the middle of the bar whenever possible.
121 It can still be pushed around if other blocks need more space. When
122 false, the center block is centered in the space between the left
123 and right block.
124 passthrough
126 typeof: bool
127 default: false
128 Option to pass any pointer events to the window under the bar.
129 Intended to be used with either top or overlay layers and without
130 exclusive zone.
131 gtk-layer-shell
133 typeof: bool
134 default: true
135 Option to disable the use of gtk-layer-shell for popups.
136 Only functional if compiled with gtk-layer-shell support.
137 ipc
139 typeof: bool
140 default: false
141 Option to subscribe to the Sway IPC bar configuration and visibil‐
142 ity events and control waybar with swaymsg bar commands.
143 Requires bar_id value from sway configuration to be either passed
144 with the -b command line argument or specified with the id option.
145 id
147 typeof: string
148 bar_id for the Sway IPC. Use this if you need to override the
149 value passed with the -b bar_id command line argument for the specific
150 bar instance.
151 include
153 typeof: string|array
154 Paths to additional configuration files.
155 Each file can contain a single object with any of the bar configu‐
156 ration options. In case of duplicate options, the first defined
157 value takes precedence, i.e. including file -> first included file
158 -> etc. Nested includes are permitted, but make sure to avoid cir‐
159 cular imports. For a multi-bar config, the include directive af‐
160 fects only current bar configuration object.
161
163 You can use PangoMarkupFormat (See https://devel‐
164 oper.gnome.org/pango/stable/PangoMarkupFormat.html#PangoMarkupFormat).
165 e.g.
167 "format": "<span style="italic">{}</span>"
169
171 If you want to have a second instance of a module, you can suffix it by
172 a '#' and a custom name. For example, if you want a second battery mod‐
173 ule, you can add "battery#bat2" to your modules. To configure the newly
174 added module, you then also add a module configuration with the same
175 name.
176 This could then look something like this (this is an incomplete exam‐
178 ple):
179 "modules-right": ["battery", "battery#bat2"],
181 "battery": {
182 "bat": "BAT1"
183 },
184 "battery#bat2": {
185 "bat": "BAT2"
186 }
187
189 A minimal config file could look like this:
190 {
192 "layer": "top",
193 "modules-left": ["sway/workspaces", "sway/mode"],
194 "modules-center": ["sway/window"],
195 "modules-right": ["battery", "clock"],
196 "sway/window": {
197 "max-length": 50
198 },
199 "battery": {
200 "format": "{capacity}% {icon}",
201 "format-icons": ["", "", "", "", ""]
202 },
203 "clock": {
204 "format-alt": "{:%a, %d. %b %H:%M}"
205 }
206 }
207
209 Limit a configuration to some outputs
210 {
211 "layer": "top",
212 "output": "eDP-1",
213 "modules-left": ["sway/workspaces", "sway/mode"],
214 ...
215 }
217 {
220 "layer": "top",
221 "output": ["eDP-1", "VGA"],
222 "modules-left": ["sway/workspaces", "sway/mode"],
223 ...
224 }
225 Configuration of multiple outputs
228 Don't specify an output to create multiple bars on the same screen.
229 [{
231 "layer": "top",
232 "output": "eDP-1",
233 "modules-left": ["sway/workspaces", "sway/mode"],
234 ...
235 }, {
236 "layer": "top",
237 "output": "VGA",
238 "modules-right": ["clock"],
239 ...
240 }]
241 Rotating modules
244 When positioning Waybar on the left or right side of the screen, some‐
245 times it's useful to be able to rotate the contents of a module so the
246 text runs vertically. This can be done using the "rotate" property of
247 the module. Example:
248 {
250 "clock": {
251 "rotate": 90
252 }
253 }
254 Valid options for the "rotate" property are: 0, 90, 180, and 270.
256 Grouping modules
258 Module groups allow stacking modules in any direction. By default, when
259 the bar is positioned on the top or bottom of the screen, modules in a
260 group are stacked vertically. Likewise, when positioned on the left or
261 right, modules in a group are stacked horizontally. This can be changed
262 with the "orientation" property.
263 A module group is defined by specifying a module named "group/some-
265 group-name". The group must also be configured with a list of contained
266 modules. Example:
267 {
269 "modules-right": ["group/hardware", "clock"],
270 "group/hardware": {
272 "orientation": "vertical",
273 "modules": [
274 "cpu",
275 "memory",
276 "battery"
277 ]
278 },
279 ...
281 }
282 Valid options for the (optional) "orientation" property are: "horizon‐
284 tal", "vertical", "inherit", and "orthogonal" (default).
285 Group Drawers
287 A group may hide all but one element, showing them only on mouse hover.
288 In order to configure this, you can use the `drawer` property, whose
289 value is an object with the following properties:
290 transition-duration:
292 typeof: integer
293 default: 500
294 Defines the duration of the transition animation in milliseconds.
295 children-class:
297 typeof: string
298 default: "hidden"
299 Defines the CSS class to be applied to the hidden elements.
300 transition-left-to-right:
302 typeof: bool
303 default: true
304 Defines the direction of the transition animation. If true, the
305 hidden elements will slide from left to right. If false, they will
306 slide from right to left.
307 When the bar is vertical, it reads as top-to-bottom.
308 "group/power": {
310 "orientation": "inherit",
311 "drawer": {
312 "transition-duration": 500,
313 "children-class": "not-power",
314 "transition-left-to-right": false,
315 },
316 "modules": [
317 "custom/power", // First element is the "group leader" and won't ever be hidden
318 "custom/quit",
319 "custom/lock",
320 "custom/reboot",
321 ]
322 },
323
325 • waybar-backlight(5)
326 • waybar-battery(5)
327 • waybar-bluetooth(5)
328 • waybar-cava(5)
329 • waybar-clock(5)
330 • waybar-cpu(5)
331 • waybar-custom(5)
332 • waybar-disk(5)
333 • waybar-dwl-tags(5)
334 • waybar-gamemode(5)
335 • waybar-hyprland-language(5)
336 • waybar-hyprland-submap(5)
337 • waybar-hyprland-window(5)
338 • waybar-hyprland-workspaces(5)
339 • waybar-idle-inhibitor(5)
340 • waybar-image(5)
341 • waybar-inhibitor(5)
342 • waybar-jack(5)
343 • waybar-keyboard-state(5)
344 • waybar-memory(5)
345 • waybar-mpd(5)
346 • waybar-mpris(5)
347 • waybar-network(5)
348 • waybar-pulseaudio(5)
349 • waybar-river-layout(5)
350 • waybar-river-mode(5)
351 • waybar-river-tags(5)
352 • waybar-river-window(5)
353 • waybar-sndio(5)
354 • waybar-states(5)
355 • waybar-sway-language(5)
356 • waybar-sway-mode(5)
357 • waybar-sway-scratchpad(5)
358 • waybar-sway-window(5)
359 • waybar-sway-workspaces(5)
360 • waybar-temperature(5)
361 • waybar-tray(5)
362 • waybar-upower(5)
363 • waybar-wireplumber(5)
364 • waybar-wlr-taskbar(5)
365 • waybar-wlr-workspaces(5)
366
369 sway-output(5)
370 2023-11-05 waybar(5)