Configuration

Config file

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

Valid directories for this file are:

• ~/.config/waybar/
• ~/waybar/
• /etc/xdg/waybar/

A good starting point is the default config.

Also a minimal example config can be found on the bottom of this page.

All valid options for the modules are listed on the modules page.

Bar Config

option	typeof	default	description
layer	string	bottom	Decide if the bar is displayed in front (top) of the windows or behind (bottom) them.
output	string	array
position	string	top	Bar position, can be top,bottom,left,right.
height	integer		Height to be used by the bar if possible, leave blank for a dynamic value.
width	integer		Width to be used by the bar if possible, leave blank for a dynamic value.
modules-left	array		Modules that will be displayed on the left.
modules-center	array		Modules that will be displayed in the center.
modules-right	array		Modules that will be displayed on the right.
margin	string		Margins value using the css format without units.
margin-<top|left|bottom|right>	integer		Margins value without units.
spacing	integer	4	Size of gaps in between of the different modules.
name	string		Optional name added as a CSS class, for styling multiple waybars.
mode	string		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. Note: hide and invisible modes may be not as useful without Sway IPC.
exclusive	bool	true	Option to request an exclusive zone from the compositor. Disable this to allow drawing application windows underneath or on top of the bar. Disabled by default for overlay layer.
passthrough	bool	false	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. Enabled by default for overlay layer.
gtk-layer-shell	bool	true	Option to disable the use of gtk-layer-shell for popups. Only functional if compiled with gtk-layer-shell support.
ipc	bool	false	Option to subscribe to the Sway IPC bar configuration and visibility events and control waybar with swaymsg bar commands. Requires bar_id value from sway configuration to be either passed with the -b commandline argument or specified with the id option. See #1244 for the documentation and configuration examples.
id	string		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.
include	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.

Module format

You can use 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"
}

To style in in styles.css use :

battery.bat2 {
    border-bottom: 2px solid #FFFFFF;
}

Minimal config

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 config

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"],
    //...
}]

You can also exclude specific output(s) by using exclamation mark, for example:

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

This will show the first bar on eDP-1, and the second bar on every output expect eDP-1

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.