waybar-custom(5)              File Formats Manual             waybar-custom(5)

<?><?><?> (NAME)
       waybar-custom - <?><?><?><?><?> <?><?><?><?><?><?> (custom) <?><?>
       waybar

<?><?><?><?><?><?><?> (DESCRIPTION)
       <?><?><?><?><?> custom <?><?><?><?><?> <?><?> <?><?><?><?><?><?><?>
       <?><?> <?><?><?> <?><?><?><?><?> (static) <?><?> <?><?><?><?><?>
       <?><?><?><?><?><?>. <?><?><?><?> <?><?><?><?><?> <?><?><?>
       <?><?><?><?><?><?> <?><?><?> <?><?><?><?> format <?><?> <?><?><?><?>
       <?><?><?><?>.

<?><?><?><?><?><?><?><?> (CONFIGURATION)
       <?><?> custom/<name> <?><?><?><?><?><?><?><?> <?><?><?><?><?><?>.

       exec:
       <?><?><?>: <?><?><?><?> (string)
       <?><?><?><?> <?><?><?><?><?><?><?><?> <?><?> <?><?><?><?> <?><?><?><?>
       <?><?><?>.

       exec-if:
       <?><?><?>: <?><?><?><?> (string)
       <?><?><?><?> <?><?><?><?><?><?><?><?> <?><?> <?><?><?><?>
       <?><?><?><?><?><?> <?><?><?> <?><?><?><?><?><?><?> <?><?><?><?><?>
       <?><?> exec <?><?><?><?> <?><?><?><?> <?><?><?> <?><?> <?><?><?>.
       <?><?><?> <?><?> <?><?><?><?> (exit code) <?><?><?><?><?><?><?> exec-if
       <?><?><?><?><?> 0 <?><?><?><?><?> exec <?><?><?><?> <?><?><?><?><?>
       <?><?>.

       hide-empty-text:
       <?><?><?>: <?><?><?><?> (bool)
       <?><?><?><?><?><?> <?><?> <?><?><?><?><?> <?><?><?><?> <?><?><?><?><?>
       <?><?><?><?><?> <?><?> <?><?><?><?><?><?><?> <?><?><?><?><?><?><?>
       <?><?><?> <?><?><?> <?><?><?><?> (format) <?><?><?><?>
       <?><?><?><?><?><?> <?><?><?><?><?><?> <?><?><?><?><?> <?><?><?><?>.

       exec-on-event:
       <?><?><?>: <?><?><?><?> (bool)
       <?><?><?><?><?><?><?>: true
       <?><?><?> <?><?> <?><?><?><?><?> <?><?><?><?><?><?> <?><?><?><?><?>
       <?><?><?> <?><?><?><?> (<?><?><?><?><?> on-click <?><?>
       on-scroll-up)<?> <?><?> <?><?> <?><?><?><?><?> <?><?><?><?><?>
       <?><?><?><?><?><?><?> <?><?><?><?><?><?><?> <?><?> <?><?><?><?><?><?>
       <?><?><?><?> <?><?><?><?><?><?>.

       return-type:
       <?><?><?>: <?><?><?><?> (string)
       <?><?> <?><?><?> <?><?><?> <?><?><?><?><?><?><?> (RETURN-TYPE)
       <?><?><?><?><?><?> <?><?><?><?>.

       interval:
       <?><?><?>: <?><?><?> <?><?><?><?> <?><?> <?><?><?><?> <?><?><?><?><?>
       (integer or float)
       <?><?><?><?> <?><?><?><?><?> (<?><?> <?><?><?> <?><?><?><?><?>) <?><?>
       <?><?><?><?><?><?><?> <?><?> <?><?> <?><?> <?><?><?><?>
       <?><?><?><?><?><?><?> <?><?><?><?><?><?> <?><?><?><?><?><?><?> (poll).
       <?><?><?><?><?> <?><?><?><?><?> 0.001 (<?><?>
       <?><?><?><?><?><?><?><?><?><?>) <?><?><?>. <?><?><?><?><?><?>
       <?><?><?><?><?><?><?> <?><?> 1ms <?><?> 1ms <?><?><?><?><?>
       <?><?><?><?><?><?> <?><?>.
       <?><?><?> <?><?><?><?><?><?><?><?><?> <?><?><?><?><?> <?><?><?>
       <?><?><?><?><?> <?><?><?><?><?><?><?><?><?><?> <?><?><?><?>
       <?><?><?><?> <?><?> once <?><?><?><?><?><?><?> <?><?><?><?>.
       <?><?><?><?><?><?><?><?><?> <?><?> <?><?> <?><?> <?><?><?><?>
       <?><?><?><?> <?><?> <?><?> <?><?><?><?><?><?>
       <?><?><?><?><?><?><?><?><?><?><?> <?><?><?><?>. <?><?><?> <?><?><?>
       interval <?><?> signal <?><?><?><?><?> <?><?><?><?> <?><?><?><?><?>
       <?><?><?> <?><?><?><?><?><?> <?><?> <?><?><?> <?><?><?><?><?><?><?>
       <?><?><?><?><?> <?><?> <?><?> <?><?><?><?> <?><?><?><?>
       <?><?><?><?><?><?>.
       <?><?><?> <?><?> signal <?><?><?><?><?> <?><?><?> <?><?><?><?><?>
       <?><?><?><?><?><?><?> <?><?> <?><?><?> <?><?><?><?><?>
       <?><?><?><?><?><?><?><?><?><?> <?><?><?><?> <?><?><?> <?> <?><?><?>
       <?><?> <?><?><?><?><?><?> <?><?><?><?><?><?>
       <?><?><?><?><?><?><?><?><?><?><?> <?><?><?><?><?> <?><?>.

       restart-interval:
       <?><?><?>: <?><?><?> <?><?><?><?> <?><?> <?><?><?><?> <?><?><?><?><?>
       (integer or float)
       <?><?><?><?> <?><?><?><?><?> <?><?><?><?><?><?><?><?><?><?>
       <?><?><?><?> (<?><?> <?><?><?> <?><?><?><?><?>).
       <?><?><?><?><?> <?><?><?><?><?> 0.001 (<?><?>
       <?><?><?><?><?><?><?><?><?><?>) <?><?><?>. <?><?><?><?><?><?>
       <?><?><?><?><?><?><?> <?><?> 1ms <?><?> 1ms <?><?><?><?><?>
       <?><?><?><?><?><?> <?><?>.
       <?><?><?><?><?><?><?><?><?> <?><?><?><?><?> <?><?> <?><?><?><?><?>
       interval <?><?><?><?><?><?><?> <?><?><?><?> <?><?><?><?><?><?><?><?>
       <?><?><?> <?><?><?><?> <?><?><?><?><?><?><?><?><?><?><?>
       <?><?><?><?><?><?> (continuous) <?><?><?><?><?><?> <?><?><?><?>.
       <?><?> <?><?><?> <?><?><?><?> <?><?><?><?><?><?><?><?> <?><?> <?><?>
       <?><?><?><?> <?><?><?><?> restart-interval <?><?><?><?><?><?>
       <?><?><?><?> <?><?><?><?><?> <?><?>.

       signal:
       <?><?><?>: <?><?><?> <?><?><?><?> (integer)
       <?><?><?><?><?> <?><?><?><?><?><?> <?><?><?><?> <?><?><?><?><?><?><?>
       <?><?><?><?> <?><?><?><?><?><?><?><?><?><?><?> <?><?><?><?><?>.
       <?><?><?> <?><?><?> <?><?><?> 1 <?> N <?><?><?><?><?> <?><?><?><?>
       <?><?> <?><?><?><?> <?><?> SIGRTMIN+N = SIGRTMAX.
       <?><?><?> <?><?><?> <?><?><?><?><?><?><?> <?><?><?><?><?> <?><?><?><?>
       <?><?><?><?><?> <?><?><?><?><?><?> <?><?><?><?> <?><?><?> <?><?><?><?>
       <?><?><?><?><?><?><?><?><?><?><?> <?><?><?><?><?> <?><?><?><?><?>
       <?><?><?>.

       format:
       <?><?><?>: <?><?><?><?> (string)
       <?><?><?><?><?><?><?>: {text}
       <?><?><?><?> <?><?><?><?> <?><?><?><?><?> <?><?><?><?><?><?><?>.
       <?><?><?><?><?><?><?> <?><?> <?><?><?> {text} <?><?><?>
       <?><?><?><?><?><?><?>.

       format-icons:
       <?><?><?>: <?><?><?><?><?> (array)
       <?><?> <?><?><?><?> <?><?><?><?> <?><?><?><?><?><?><?><?><?><?>
       <?><?><?><?><?> <?><?><?><?><?><?> <?><?><?><?><?><?>
       <?><?><?><?><?><?>. <?><?><?><?><?> <?><?> low (<?><?>) <?><?> high
       (<?><?><?><?>) <?><?><?>.

       rotate:
       <?><?><?>: <?><?><?> <?><?><?><?> (integer)
       <?><?><?><?><?> <?><?><?><?> <?><?><?><?> <?><?><?><?><?><?><?>
       <?><?><?><?><?> <?><?><?><?> (<?><?> <?><?><?><?><?><?><?> <?><?>
       <?><?><?><?>).

       max-length:
       <?><?><?>: <?><?><?> <?><?><?><?> (integer)
       <?><?><?><?><?><?> <?><?><?> <?><?> <?><?><?> <?><?><?><?><?><?><?>
       <?><?> <?><?><?><?><?> <?><?><?><?> <?><?><?><?><?> <?><?><?>.

       min-length:
       <?><?><?>: <?><?><?> <?><?><?><?> (integer)
       <?><?><?><?><?> <?><?><?> <?><?> <?><?><?> <?><?><?><?><?><?><?> <?><?>
       <?><?><?><?><?> <?><?><?><?> <?><?><?><?><?><?>.

       align:
       <?><?><?>: <?><?><?><?> <?><?><?><?><?> (float)
       <?><?><?><?> <?><?><?><?><?> <?><?><?><?> <?><?><?><?><?><?> <?><?>
       <?><?> <?><?> 0 <?><?><?><?><?><?> <?> 1 <?><?><?><?><?><?><?><?>
       <?><?><?>. <?><?><?> <?><?><?><?><?> <?><?><?><?><?><?><?> <?><?><?><?>
       <?><?> <?><?><?> <?><?><?> <?><?><?><?><?> <?><?><?><?><?><?>.

       justify:
       <?><?><?>: <?><?><?><?> (string)
       <?><?><?><?> <?><?><?> <?><?><?><?> <?><?><?><?><?> <?><?><?><?><?><?>
       <?><?> <?><?><?><?><?><?><?><?><?> 'left' (<?><?>)<?> 'right'
       (<?><?><?><?>) <?><?> 'center' (<?><?><?>) <?><?> <?><?><?><?>
       <?><?><?><?><?> <?><?><?><?><?><?> <?><?><?><?><?><?><?><?>.

       on-click:
       <?><?><?>: <?><?><?><?> (string)
       <?><?><?><?><?><?> <?><?> <?><?><?><?><?> <?><?><?><?> <?><?><?>
       <?><?><?><?><?> <?><?><?><?> <?><?><?><?><?><?>.

       on-click-middle:
       <?><?><?>: <?><?><?><?> (string)
       <?><?><?><?><?><?> <?><?> <?><?><?><?><?> <?><?><?><?> <?><?><?><?><?>
       <?><?> <?><?><?> <?><?><?><?> <?><?><?> <?><?><?><?><?> <?><?><?><?>
       <?><?><?><?><?><?>.

       on-click-right:
       <?><?><?>: <?><?><?><?> (string)
       <?><?><?><?><?><?> <?><?> <?><?><?><?><?> <?><?><?><?><?><?><?><?><?>
       <?><?><?> <?><?><?><?><?> <?><?><?><?> <?><?><?><?><?><?>.

       on-update:
       <?><?><?>: <?><?><?><?> (string)
       <?><?><?><?><?><?> <?><?> <?><?><?><?><?>
       <?><?><?><?><?><?><?><?><?><?><?> <?><?><?><?><?> <?><?><?><?>
       <?><?><?><?><?><?>.

       on-scroll-up:
       <?><?><?>: <?><?><?><?> (string)
       <?><?><?><?><?><?> <?><?> <?><?><?><?><?> <?><?><?><?><?><?> <?><?>
       <?><?><?><?> <?><?><?> <?><?><?><?><?> <?><?><?><?> <?><?><?><?><?><?>.

       on-scroll-down:
       <?><?><?>: <?><?><?><?> (string)
       <?><?><?><?><?><?> <?><?> <?><?><?><?><?> <?><?><?><?><?><?> <?><?>
       <?><?><?><?><?> <?><?><?> <?><?><?><?><?> <?><?><?><?>
       <?><?><?><?><?><?>.

       smooth-scrolling-threshold:
       <?><?><?>: <?><?><?><?> <?><?><?><?><?> <?><?> <?><?><?>
       <?><?><?><?><?> (double)
       <?><?><?><?><?><?> <?><?><?><?> <?><?><?><?><?><?><?> <?><?><?><?><?>
       <?><?><?><?><?><?>.

       tooltip:
       <?><?><?>: <?><?><?><?> (bool)
       <?><?><?><?><?><?><?>: true
       <?><?><?><?><?><?><?><?> <?><?><?><?> <?><?><?><?><?><?><?>
       <?><?><?><?> <?><?><?><?><?><?><?> <?><?><?><?><?> (tooltip) <?><?>
       <?><?><?><?><?> <?><?><?> <?><?><?><?><?> <?><?><?><?>.

       tooltip-format:
       <?><?><?>: <?><?><?><?> (string)
       <?><?><?><?> <?><?><?><?><?><?><?> <?><?><?><?><?> (tooltip). <?><?>
       <?><?><?><?> <?><?><?><?><?><?> <?><?> <?><?><?><?><?><?>
       <?><?><?><?><?> <?><?><?><?><?><?><?> <?><?><?><?><?>
       <?><?><?><?><?><?><?><?><?> <?><?> <?><?><?><?><?><?><?>
       <?><?><?><?><?> <?><?> exec <?><?><?><?><?><?> <?><?><?><?>.
       <?><?> <?><?><?><?> <?><?><?><?><?><?><?><?><?><?><?> <?><?><?><?>
       format <?><?><?><?><?><?><?> <?><?><?><?><?><?>.

       escape:
       <?><?><?>: <?><?><?><?> (bool)
       <?><?><?><?><?><?><?>: false
       <?><?><?><?><?><?><?><?> <?><?><?><?> <?><?><?><?> <?><?><?><?>
       <?><?><?><?><?><?><?><?><?><?> (escaping) <?><?><?><?><?><?><?><?><?>
       <?><?> <?><?><?><?><?> <?><?><?><?><?><?><?>.

       menu:
       <?><?><?>: <?><?><?><?> (string)
       <?><?><?><?> <?><?> <?><?><?> <?><?> <?><?><?> <?><?><?><?><?><?>.

       menu-file:
       <?><?><?>: <?><?><?><?> (string)
       <?><?><?><?> <?><?><?><?> <?><?><?><?><?><?><?><?><?><?><?> <?><?><?>.
       <?><?><?><?> <?><?><?><?><?> <?><?> <?><?><?>
           GtkMenu <?><?> <?><?><?><?><?> menu <?><?><?><?> <?><?><?><?><?>
           <?><?><?><?>.

       menu-actions:
       <?><?><?>: <?><?><?><?><?> (array)
       <?><?><?><?><?><?><?> <?><?><?><?><?><?> <?><?>
       <?><?><?><?><?><?><?><?> <?><?><?>.

       expand:
       <?><?><?>: <?><?><?><?> (bool)
       <?><?><?><?><?><?><?>: false
       <?><?><?><?><?> <?><?><?><?> <?><?><?><?><?> <?><?><?><?><?>
       <?><?><?><?> <?><?><?><?><?><?><?><?><?><?> <?><?><?><?> <?><?><?>
       <?><?><?><?><?> <?><?> <?><?><?><?> <?><?><?><?><?><?>.

<?><?><?> <?><?><?><?><?><?><?> (RETURN-TYPE)
       <?><?><?><?><?><?> <?><?> return-type <?><?> <?><?><?> json
       <?><?><?><?><?> <?><?><?><?> Waybar <?><?><?><?><?><?> <?><?><?><?>
       <?><?> <?><?><?><?><?><?><?> exec <?><?><?><?><?><?><?><?> <?><?><?>
       <?><?> <?><?> <?><?><?><?> JSON <?><?><?><?><?> <?><?><?>. <?><?><?>
       <?><?><?><?><?> <?><?><?><?> <?><?> <?><?><?> <?><?><?> <?><?><?><?>:

           {"text": "$text", "tooltip": "$tooltip", "class": "$class", "percentage": $percentage }

       <?><?><?><?><?><?><?> class <?><?><?><?><?><?> <?><?><?><?><?><?><?><?>
       <?><?> <?><?><?><?><?><?><?> <?><?> <?><?><?><?><?><?><?><?>.

       <?><?><?> <?><?><?><?> <?><?><?><?> <?><?><?><?> <?><?><?><?> <?><?>
       <?><?> <?><?><?><?><?> <?><?><?><?><?><?><?> <?><?><?><?><?>
       <?><?><?><?> Waybar <?><?><?><?><?><?> <?><?><?><?><?> <?><?> <?><?><?>
       i3blocks <?><?> <?><?><?><?>. <?><?><?><?><?><?> <?><?> <?><?>
       <?><?><?><?> (newline) <?><?> <?><?><?><?><?><?> <?><?><?>
       <?><?><?><?><?><?><?>. <?><?><?> <?><?><?><?><?> <?><?><?><?> <?><?>
       <?><?><?> <?><?><?> <?><?><?><?>:

           $text0tooltip0class*

       class <?><?> <?><?><?><?> CSS <?><?><?><?> <?><?><?><?> <?><?><?><?><?>
       <?><?><?><?><?><?><?><?><?><?> <?><?><?><?><?><?><?> <?><?> style.css

<?><?><?><?><?><?><?><?><?><?><?> <?><?><?><?><?><?><?><?><?> (FORMAT
       REPLACEMENTS)
       {text}: <?><?><?><?><?> <?><?><?><?><?><?><?>.

       {percentage}: <?><?><?><?><?> <?><?> <?><?><?><?><?><?><?><?> <?><?>
       <?><?><?><?> <?><?><?> <?><?><?><?><?><?><?> json <?><?><?><?><?>
       <?><?><?>.

       {icon}: <?><?> <?><?><?><?><?> <?><?> 'format-icons' <?><?>
       <?><?><?><?> <?><?><?><?>.

<?><?><?><?><?><?><?> (EXAMPLES)
   Spotify:
           "custom/spotify": {
                "format": "<?> {text}",
                "max-length": 40,
                "interval": 30, // Remove this if your script is endless and write in loop
                "exec": "$HOME/.config/waybar/mediaplayer.sh 2> /dev/null", // Script in resources folder
                "exec-if": "pgrep spotify",
                "return-type": "json"
           }

   mpd:
           "custom/mpd": {
                "format": "<?> {text}",
                //"max-length": 15,
                "interval": 10,
                "exec": "mpc current",
                "exec-if": "pgrep mpd",
                "on-click": "mpc toggle",
                "on-click-right": "sonata"
           }

   cmus:
           "custom/cmus": {
                "format": "<?> {text}",
                //"max-length": 15,
                "interval": 10,
                "exec": "cmus-remote -C "format_print '%a - %t'"", // artist - title
                "exec-if": "pgrep cmus",
                "on-click": "cmus-remote -u",                        //toggle pause
                "escape": true                                       //handle markup entities
           }

   Pacman

           "custom/pacman": {
                "format": "{text}  <?>",
                "interval": "once",
                "exec": "pacman_packages",
                "on-click": "update-system",
                "signal": 8
           }

   Alternate Pacman
           "custom/pacman": {
                "format": "{text}  <?>",
                "exec": "checkupdates | wc -l",       // # of updates
                "exec-if": "exit 0",                  // always run; consider advanced run conditions
                "on-click": "termite -e 'sudo pacman -Syu'; pkill -SIGRTMIN+8 waybar", // update system
                "signal": 8
           }

       <?><?> <?><?><?> <?><?><?> <?><?> <?><?><?><?> <?><?><?><?><?>
       (interval) <?><?><?><?><?> <?><?><?><?> <?><?><?><?>
       <?><?><?><?><?><?><?><?><?> <?><?> <?><?><?><?><?><?>
       <?><?><?><?><?><?><?> <?><?><?><?> <?> <?><?><?><?><?>
       <?><?><?><?><?><?><?><?> <?><?><?><?><?> <?><?> <?><?> pkill -RTMIN+8
       waybar <?><?><?><?><?><?><?><?><?><?><?> <?><?><?><?>.

<?><?><?><?><?><?> (STYLE)
       o   #custom-<name>
       o   #custom-<name>.<class>
       o   <class> <?><?><?><?><?><?><?><?> <?><?><?><?> <?><?><?><?><?><?><?>
           <?><?><?><?><?> <?><?><?>. <?><?><?><?> <?><?><?><?><?><?><?>
           <?><?><?><?><?> <?><?> <?><?><?> <?><?><?> <?><?><?><?><?><?><?>
           (RETURN-TYPE) <?><?><?><?><?><?> <?><?><?><?>.

                                  2026-08-31                  waybar-custom(5)