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 on the at the bottom of this
23 man 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 of 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 commandline 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 commandline 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 the direction orthogonal to the
259 bar direction. When the bar is positioned on the top or bottom of the
260 screen, modules in a group are stacked vertically. Likewise, when posi‐
261 tioned on the left or right, modules in a group are stacked horizon‐
262 tally.
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
287 • waybar-backlight(5)
288 • waybar-battery(5)
289 • waybar-bluetooth(5)
290 • waybar-cava(5)
291 • waybar-clock(5)
292 • waybar-cpu(5)
293 • waybar-custom(5)
294 • waybar-disk(5)
295 • waybar-idle-inhibitor(5)
296 • waybar-image(5)
297 • waybar-keyboard-state(5)
298 • waybar-memory(5)
299 • waybar-mpd(5)
300 • waybar-mpris(5)
301 • waybar-network(5)
302 • waybar-pulseaudio(5)
303 • waybar-river-mode(5)
304 • waybar-river-tags(5)
305 • waybar-river-window(5)
306 • waybar-river-layout(5)
307 • waybar-states(5)
308 • waybar-sway-mode(5)
309 • waybar-sway-scratchpad(5)
310 • waybar-sway-window(5)
311 • waybar-sway-workspaces(5)
312 • waybar-wireplumber(5)
313 • waybar-wlr-taskbar(5)
314 • waybar-wlr-workspaces(5)
315 • waybar-temperature(5)
316 • waybar-tray(5)
317
320 sway-output(5)
321 2023-08-16 waybar(5)