Skip to content

Formatting

patrick96 edited this page May 6, 2019 · 38 revisions

Make sure you read the Configuration wiki page.

Formats

Most modules define a format-NAME field, which lets you configure the output format of the module.

For example, the mpd module defines the following formats that will be used depending on connection state

[module/mpd]
format-online = ...
format-offline = ...

All formats can be configured using the following parameters:

format-NAME = ...

; The prefix and suffix properties contains all
; properties that are available for any `<label>`.
format-NAME-prefix = ...
format-NAME-prefix-foreground = #f00
format-NAME-suffix = ...
format-NAME-suffix-background = #0f0

; By only specifying alpha value, it will be
; applied to the bar's default foreground/background color
format-NAME-foreground = #aa[rrggbb]
format-NAME-background = #aa[rrggbb]
format-NAME-underline  = #aa[rrggbb]
format-NAME-overline   = #aa[rrggbb]

; Number of whitespaces
format-NAME-padding = N
format-NAME-margin  = N
format-NAME-spacing = N

; Use Nth font for this format (1-indexed) (unreleased)
format-NAME-font = N

; Displace the format block horizontally by +/-N pixels
format-NAME-offset  = N

TODO: Improve section

Tokens

Modules define tokens that you can use as placeholders for content values.

label = %token%

; Set value min width
; If the min-width begins with a `0`, the string will be zero-padded
label = %token:3%

; Set value max width
; NOTE: the length of the token includes suffixes appended internally (KB/s, %, etc.)
label = %token:0:10%

; Specify suffix to be used if truncated to max width
label = %token:0:10:...%
label = %token:0:10:---%

Content types

Label

TODO: Improve section

label-NAME = foobar
;label-NAME-foreground = #aarrggbb
;label-NAME-background = #aarrggbb
;label-NAME-overline = #aarrggbb
;label-NAME-underline = #aarrggbb
;label-NAME-font = N

; Add N spaces to the left and right of the label contents
; Default: 0
label-NAME-padding = N

; Truncate text if it exceeds given limit. 
; Default: 0
label-NAME-maxlen = 30

; Optionally append ... to the truncated string.
; Default: true
label-NAME-ellipsis = false

Progressbar

TODO: Improve section

bar-NAME-format = %fill%%indicator%%empty%
bar-NAME-width = 10

bar-NAME-gradient = true
bar-NAME-foreground-0 = #00ff00
bar-NAME-foreground-1 = #ff9900
bar-NAME-foreground-2 = #ff0000

; The fill, indicator and empty icon can be configured like any <label>
bar-NAME-fill = x
bar-NAME-indicator = x
bar-NAME-empty = x

Ramp

TODO: Improve section

ramp-NAME-0 = 🔈
ramp-NAME-1 = 🔉
ramp-NAME-2 = 🔊

Ramp entries are based on labels which means that you can define all properties that are available for a <label>, for example:

ramp-NAME-0-foreground = #00f
ramp-NAME-1-background = #f90

To avoid repetition it's possible to define default values for each entry on the <ramp> itself. The following would set the background/foreground color for all entries with a custom foreground color for ramp-NAME-0.

ramp-NAME-background = #fff
ramp-NAME-foreground = #000
ramp-NAME-0 = A
ramp-NAME-0-foreground = #f00
ramp-NAME-1 = B
ramp-NAME-2 = C

Animation

TODO: Improve section

Format tags

Polybar has built-in support for basic lemonbar tags.

NOTE: The %{U} tag has been replaced by %{u#hex} and %{o#hex} to allow changing under-/overline color independently.

A script that is called from a custom/script module can wrap its output (or parts of it) in these format tags to change how polybar displays the text in between them.

Format tags inside polybar config

Of course you can use the format tags inside other modules also, but since most format- field have their own foreground, background, etc suffixes, this often is not necessary. One use case is to style only parts of a label, for example if in the volume module you wanted to only display the percentage in a certain color but not the percent sign, you could use the foreground tag like this:

label-volume = %{F#f00}%percentage%%{F-}%

Pitfalls: As described in #615 using polybar variables inside format tags is not possible. So something like this won't work:

label = "Some text %{F${colors.foreground-alt}}Colored%{F-}"

If you want this behaviour, you'll need to define the whole label string, with the color codes, in an environment variable before you start the bar and then reference that variable inside the config like this:

export BAR_MODULE_LABEL="Some text %{F$COLOR_FG_ALT}Colored%{F-}"

This means, you will also have to define the colors as environment variables.

And inside the polybar config:

...
label = ${env:BAR_MODULE_LABEL}
...

Foreground color %{F}

%{F#f00} red text %{F-} default text

Background color %{B}

%{B#f00}%{F#000} black text on red background %{B- F-}

Reverse back-/foreground colors %{R}

black bg, white fg %{R} white bg, black fg

Underline color %{u}

%{u#ff9900}%{+u} orange underline %{u#0000ff} blue underline %{u-} default underline color %{-u} underline disabled

Overline color %{o}

%{o#ff9900}%{+o} orange overline %{o#0000ff} blue overline %{o-} default overline color %{-o} overline disabled

Font %{T}

%{T3} Uses font-2 %{T-} use first (default) font

Notice how the font tag uses a 1-based index, same as the -font property. See also Fonts.

Offset %{O}

%{O10} pushed 10 pixels to the right %{O-5} 5 pixels to the left

Action %{A}

Actions handlers are defined using the following syntax: %{A<button-index><colon><command><colon>}<inner-text>%{A}

%{A1:command:} clickable text %{A}

Note: If command contains any colons (:), you have to escape them with a backslash like this: \:. Otherwise the colon acts as the command delimiter and polybar would only parse the command until the colon.

The following values for <button-index> are allowed:

  • 1: left click
  • 2: middle click
  • 3: right click
  • 4: scroll up
  • 5: scroll down
  • 6: double left click
  • 7: double middle click
  • 8: double right click

Note: Double click actions may not work reliably.

Nested Actions

As with any formatting tag you can also have nested action. For example:

%{A1:...:}%{A2:...:}Some clickable text%{A} only left click%{A}

The text inside both tags responds to both left and middle clicks.

If you nest actions for the same button, the innermost action tag will be chosen when clicked:

%{A1:firefox:}%{A1:chromium:}This opens chromium%{A} and this one firefox%{A}
You can’t perform that action at this time.