1waybar(5)
2
3# NAME
4
5waybar - configuration file
6
7# DESCRIPTION
8
9The configuration uses the JSON file format and is named *config*.
10
11Valid locations for this file are:
12
13- *$XDG_CONFIG_HOME/waybar/config*
14- *~/.config/waybar/config*
15- *~/waybar/config*
16- */etc/xdg/waybar/config*
17- *@sysconfdir@/xdg/waybar/config*
18
19A good starting point is the default configuration found at https://github.com/Alexays/Waybar/blob/master/resources/config
20Also a minimal example configuration can be found on the at the bottom of this man page.
21
22# BAR CONFIGURATION
23
24*layer* ++
25	typeof: string ++
26	default: bottom ++
27	Decide if the bar is displayed in front (*top*) of the windows or behind (*bottom*)
28	them.
29
30*output* ++
31	typeof: string|array ++
32	Specifies on which screen this bar will be displayed. Exclamation mark(*!*) can be used to exclude specific output.
33
34*position* ++
35	typeof: string ++
36	default: top ++
37	Bar position, can be *top*, *bottom*, *left*, *right*.
38
39*height* ++
40	typeof: integer ++
41	Height to be used by the bar if possible. Leave blank for a dynamic value.
42
43*width* ++
44	typeof: integer ++
45	Width to be used by the bar if possible. Leave blank for a dynamic value.
46
47*modules-left* ++
48	typeof: array ++
49	Modules that will be displayed on the left.
50
51*modules-center* ++
52	typeof: array ++
53	Modules that will be displayed in the center.
54
55*modules-right* ++
56	typeof: array
57	Modules that will be displayed on the right.
58
59*margin* ++
60	typeof: string ++
61	Margins value using the CSS format without units.
62
63*margin-<top\|left\|bottom\|right>* ++
64	typeof: integer ++
65	Margins value without units.
66
67*spacing* ++
68	typeof: integer ++
69	Size of gaps in between of the different modules.
70
71*name* ++
72	typeof: string ++
73	Optional name added as a CSS class, for styling multiple waybars.
74
75*mode* ++
76	typeof: string ++
77	Selects one of the preconfigured display modes. This is an equivalent of the sway-bar(5) *mode* command and supports the same values: *dock*, *hide*, *invisible*, *overlay*. ++
78	Note: *hide* and *invisible* modes may be not as useful without Sway IPC.
79
80*exclusive* ++
81	typeof: bool ++
82	default: *true* ++
83	Option to request an exclusive zone from the compositor. Disable this to allow drawing application windows underneath or on top of the bar.
84
85*fixed-center* ++
86	typeof: bool ++
87	default: *true*
88	Prefer fixed center position for the `modules-center` block. The center block will stay in the middle of the bar whenever possible. It can still be pushed around if other blocks need more space.
89	When false, the center block is centered in the space between the left and right block.
90
91*passthrough* ++
92	typeof: bool ++
93	default: *false* ++
94	Option to pass any pointer events to the window under the bar.
95	Intended to be used with either *top* or *overlay* layers and without exclusive zone.
96
97*gtk-layer-shell* ++
98	typeof: bool ++
99	default: true ++
100	Option to disable the use of gtk-layer-shell for popups.
101	Only functional if compiled with gtk-layer-shell support.
102
103*ipc* ++
104	typeof: bool ++
105	default: false ++
106	Option to subscribe to the Sway IPC bar configuration and visibility events and control waybar with *swaymsg bar* commands. ++
107	Requires *bar_id* value from sway configuration to be either passed with the *-b* commandline argument or specified with the *id* option.
108
109*id* ++
110	typeof: string ++
111	*bar_id* for the Sway IPC. Use this if you need to override the value passed with the *-b bar_id* commandline argument for the specific bar instance.
112
113*include* ++
114	typeof: string|array ++
115	Paths to additional configuration files.
116	Each file can contain a single object with any of the bar configuration options. In case of duplicate options, the first defined value takes precedence, i.e. including file -> first included file -> etc. Nested includes are permitted, but make sure to avoid circular imports.
117	For a multi-bar config, the include directive affects only current bar configuration object.
118
119# MODULE FORMAT
120
121You can use PangoMarkupFormat (See https://developer.gnome.org/pango/stable/PangoMarkupFormat.html#PangoMarkupFormat).
122
123e.g.
124
125```
126"format": "<span style=\"italic\">{}</span>"
127```
128# MULTIPLE INSTANCES OF A MODULE
129
130If you want to have a second instance of a module, you can suffix it by a '#' and a custom name.
131For example if you want a second battery module, you can add *"battery#bat2"* to your modules.
132To configure the newly added module, you then also add a module configuration with the same name.
133
134This could then look something like this *(this is an incomplete example)*:
135
136```
137"modules-right": ["battery", "battery#bat2"],
138"battery": {
139	"bat": "BAT1"
140},
141"battery#bat2": {
142	"bat": "BAT2"
143}
144```
145
146# MINIMAL CONFIGURATION
147
148A minimal *config* file could look like this:
149
150```
151{
152	"layer": "top",
153	"modules-left": ["sway/workspaces", "sway/mode"],
154	"modules-center": ["sway/window"],
155	"modules-right": ["battery", "clock"],
156	"sway/window": {
157		"max-length": 50
158	},
159	"battery": {
160		"format": "{capacity}% {icon}",
161		"format-icons": ["", "", "", "", ""]
162	},
163	"clock": {
164		"format-alt": "{:%a, %d. %b  %H:%M}"
165	}
166}
167```
168
169# MULTI OUTPUT CONFIGURATION
170
171## Limit a configuration to some outputs
172
173```
174{
175	"layer": "top",
176	"output": "eDP-1",
177	"modules-left": ["sway/workspaces", "sway/mode"],
178	...
179
180}
181
182```
183
184```
185{
186	"layer": "top",
187	"output": ["eDP-1", "VGA"],
188	"modules-left": ["sway/workspaces", "sway/mode"],
189	...
190}
191
192```
193
194## Configuration of multiple outputs
195
196Don't specify an output to create multiple bars on the same screen.
197
198```
199[{
200	"layer": "top",
201	"output": "eDP-1",
202	"modules-left": ["sway/workspaces", "sway/mode"],
203	...
204}, {
205	"layer": "top",
206	"output": "VGA",
207	"modules-right": ["clock"],
208	...
209}]
210
211```
212
213## Rotating modules
214
215When positioning Waybar on the left or right side of the screen, sometimes it's useful to be able to rotate the contents of a module so the text runs vertically. This can be done using the "rotate" property of the module. Example:
216
217```
218{
219	"clock": {
220		"rotate": 90
221	}
222}
223```
224
225Valid options for the "rotate" property are: 0, 90, 180 and 270.
226
227## Grouping modules
228
229Module groups allow stacking modules in the direction orthogonal to the bar direction. When the bar is positioned on the top or bottom of the screen, modules in a group are stacked vertically. Likewise, when positioned on the left or right, modules in a group are stacked horizontally.
230
231A module group is defined by specifying a module named "group/some-group-name". The group must also be configured with a list of contained modules. Example:
232
233```
234{
235	"modules-right": ["group/hardware", "clock"],
236
237	"group/hardware": {
238		"modules": [
239			"cpu",
240			"memory",
241			"battery"
242		]
243	},
244
245	...
246}
247```
248
249# SUPPORTED MODULES
250
251- *waybar-backlight(5)*
252- *waybar-battery(5)*
253- *waybar-bluetooth(5)*
254- *waybar-clock(5)*
255- *waybar-cpu(5)*
256- *waybar-custom(5)*
257- *waybar-disk(5)*
258- *waybar-idle-inhibitor(5)*
259- *waybar-keyboard-state(5)*
260- *waybar-memory(5)*
261- *waybar-mpd(5)*
262- *waybar-network(5)*
263- *waybar-pulseaudio(5)*
264- *waybar-river-tags(5)*
265- *waybar-states(5)*
266- *waybar-sway-mode(5)*
267- *waybar-sway-window(5)*
268- *waybar-sway-workspaces(5)*
269- *waybar-wlr-taskbar(5)*
270- *waybar-wlr-workspaces(5)*
271- *waybar-temperature(5)*
272- *waybar-tray(5)*
273