Waybar/man/waybar.5.scd.in

waybar(5)

# NAME

waybar - configuration file

# DESCRIPTION

The configuration uses the JSON file format and is named *config*.

Valid locations for this file are:

- *$XDG_CONFIG_HOME/waybar/config*
- *~/.config/waybar/config*
- *~/waybar/config*
- */etc/xdg/waybar/config*
- *@sysconfdir@/xdg/waybar/config*

A good starting point is the default configuration found at https://github.com/Alexays/Waybar/blob/master/resources/config
Also a minimal example configuration can be found on the at the bottom of this man page.

# BAR CONFIGURATION

*layer* ++
	typeof: string ++
	default: bottom ++
	Decide if the bar is displayed in front (*top*) of the windows or behind (*bottom*)
	them.

*output* ++
	typeof: string|array ++
	Specifies on which screen this bar will be displayed. Exclamation mark(*!*) can be used to exclude specific output.

*position* ++
	typeof: string ++
	default: top ++
	Bar position, can be *top*, *bottom*, *left*, *right*.

*height* ++
	typeof: integer ++
	Height to be used by the bar if possible. Leave blank for a dynamic value.

*width* ++
	typeof: integer ++
	Width to be used by the bar if possible. Leave blank for a dynamic value.

*modules-left* ++
	typeof: array ++
	Modules that will be displayed on the left.

*modules-center* ++
	typeof: array ++
	Modules that will be displayed in the center.

*modules-right* ++
	typeof: array
	Modules that will be displayed on the right.

*margin* ++
	typeof: string ++
	Margins value using the CSS format without units.

*margin-<top\|left\|bottom\|right>* ++
	typeof: integer ++
	Margins value without units.

*name* ++
	typeof: string ++
	Optional name added as a CSS class, for styling multiple waybars.

*exclusive* ++
	typeof: bool ++
	default: *true* unless the layer is set to *overlay* ++
	Option to request an exclusive zone from the compositor. Disable this to allow drawing application windows underneath or on top of the bar.

*passthrough* ++
	typeof: bool ++
	default: *false* unless the layer is set to *overlay* ++
	Option to pass any pointer events to the window under the bar.
	Intended to be used with either *top* or *overlay* layers and without exclusive zone.

*gtk-layer-shell* ++
	typeof: bool ++
	default: true ++
	Option to disable the use of gtk-layer-shell for popups.
	Only functional if compiled with gtk-layer-shell support.

*include* ++
	typeof: string|array ++
	Paths to additional configuration files.
	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.
	For a multi-bar config, the include directive affects only current bar configuration object.

*custom-execs* ++
	typeof: array ++
	Shared execs for custom modules.
	See the section SHARED EXECS FOR CUSTOM MODULES

# MODULE FORMAT

You can use PangoMarkupFormat (See https://developer.gnome.org/pango/stable/PangoMarkupFormat.html#PangoMarkupFormat).

e.g.

```
"format": "<span style=\"italic\">{}</span>"
```
# MULTIPLE INSTANCES OF A MODULE

If you want to have a second instance of a module, you can suffix it by a '#' and a custom name.
For example if you want a second battery module, you can add *"battery#bat2"* to your modules.
To configure the newly added module, you then also add a module configuration with the same name.

This could then look something like this *(this is an incomplete example)*:

```
"modules-right": ["battery", "battery#bat2"],
"battery": {
	"bat": "BAT1"
},
"battery#bat2": {
	"bat": "BAT2"
}
```

# MINIMAL CONFIGURATION

A minimal *config* file could look like this:

```
{
	"layer": "top",
	"modules-left": ["sway/workspaces", "sway/mode"],
	"modules-center": ["sway/window"],
	"modules-right": ["battery", "clock"],
	"sway/window": {
		"max-length": 50
	},
	"battery": {
		"format": "{capacity}% {icon}",
		"format-icons": ["", "", "", "", ""]
	},
	"clock": {
		"format-alt": "{:%a, %d. %b  %H:%M}"
	}
}
```

# MULTI OUTPUT CONFIGURATION

## Limit a configuration to some outputs

```
{
	"layer": "top",
	"output": "eDP-1",
	"modules-left": ["sway/workspaces", "sway/mode"],
	...

}

```

```
{
	"layer": "top",
	"output": ["eDP-1", "VGA"],
	"modules-left": ["sway/workspaces", "sway/mode"],
	...
}

```

## Configuration of multiple outputs

Don't specify an output to create multiple bars on the same screen.

```
[{
	"layer": "top",
	"output": "eDP-1",
	"modules-left": ["sway/workspaces", "sway/mode"],
	...
}, {
	"layer": "top",
	"output": "VGA",
	"modules-right": ["clock"],
	...
}]

```

## Rotating modules

When 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:

```
{
	"clock": {
		"rotate": 90
	}
}
```

Valid options for the "rotate" property are: 0, 90, 180 and 270.

# SHARED EXECS FOR CUSTOM MODULES

When several custom modules acquire data from the same or similar commands, it
may be desirable to execute only a single instance of the command to minimize
CPU usage. For such cases, the "custom-execs" configuration parameter of a bar
can be used.

"custom-execs" is an array of configuration objects for executed commands. Each
object may contain the following parameters:

*exec*: ++
	typeof: string ++
	The command to execute, passed as an argument to "sh -c".

*exec-if*: ++
	typeof: string ++
	The command to execute, which determines if the command in *exec* should be executed.
	*exec* will be executed if the exit code of *exec-if* equals 0.

*interval*: ++
	typeof: integer ++
	The interval (in seconds) in which the information gets polled.
	Use *once* if you want to execute the module only on startup.
	You can update it manually with a signal. If no *interval* is defined,
	it is assumed that the command loops itself.

*restart-interval*: ++
	typeof: integer ++
	The restart interval (in seconds).
	Can't be used with the *interval* option, so only with continuous scripts.
	Once the script exits, it'll be re-executed after the *restart-interval*.

*signal*: ++
	typeof: integer ++
	The signal number used to rerun the command.
	Can only be used with the *interval* option.
	The number is valid between 1 and N, where *SIGRTMIN+N* = *SIGRTMAX*.


Configuration example with two shared subprocesses:

```
"custom-execs": [
	{
		// Executed once, restarted after 5 seconds if it exits.
		"exec": "my-command arg1 arg2",
		"restart-interval": 5
	},
	{
		// foo is executed every 2 seconds, or when the signal SIGRTMIN+8 is received.
		// Each time, if foo exits with code 0, bar is executed.
		"exec-if": "foo",
		"exec": "bar",
		"interval": 2,
		"signal": 8
	}
]
```

The command specified in *exec* must provide a single line of JSON output.
If the command is continuous (no *interval*), it should provide a single line
of JSON output for each update. The JSON should contain an object with module
names as keys and either strings (for raw output) or objects (for JSON output)
as values. See waybar-custom(5) for a description of the formats.

Output example (spread over several lines for readability; the actual command
should print it on one line):

```
{
	"custom/xyz#abc": {
		"text": "some text to show",
		"alt": "some other text",
		"tooltip": "tooltip text",
		"percentage": 5,
	},
	"custom/qwerty": "asdf\\nzxcv\\nmyclass\\n"
}
```

The output may contain any number of modules. The modules do not have to stay
constant between output lines. Each module in the output line will be updated.

# SUPPORTED MODULES

- *waybar-backlight(5)*
- *waybar-battery(5)*
- *waybar-bluetooth(5)*
- *waybar-clock(5)*
- *waybar-cpu(5)*
- *waybar-custom(5)*
- *waybar-disk(5)*
- *waybar-idle-inhibitor(5)*
- *waybar-keyboard-state(5)*
- *waybar-memory(5)*
- *waybar-mpd(5)*
- *waybar-network(5)*
- *waybar-pulseaudio(5)*
- *waybar-river-tags(5)*
- *waybar-states(5)*
- *waybar-sway-mode(5)*
- *waybar-sway-window(5)*
- *waybar-sway-workspaces(5)*
- *waybar-wlr-taskbar(5)*
- *waybar-temperature(5)*
- *waybar-tray(5)*