waybar-clock(5)

📦
version 0.15.0 · 13 versions
, in ubuntu resolute, ubuntu stonking

✨ NAME ✨

okay so bestie, this is waybar-clock — it's the clock module for waybar 💖 (like, the bar itself is waybar, and this is the clock part of it, iykyk).

🌸 DESCRIPTION 🌸

The clock module is literally the main character that just... shows you the current date and time 🕐✨ That's it. That's the whole job. It's giving simple, it's giving reliable, it's giving "what time is it bestie" energy and honestly? Obsessed. 💅

🎀 FILES 🎀

  • $XDG_CONFIG_HOME/waybar/config — the per-user configuration file, aka where you get to tell the clock module what to do 🫶 this is your config era, your moment, your time to shine 🌟
Heads up bestie: $XDG_CONFIG_HOME is an environment variable, so it expands to whatever your system says it is (for a lot of people that's ~/.config, but don't @ me — check your env, fr fr) 💀

💖 CONFIGURATION 💖

  1. Addressed by clock

okay bestie, these are your settings for the clock module, the ones you drop inside "clock": { ... }. every single one, no skips, let's go 🫶

  • interval (integer, default 60) — how often (in, like, a unit of time) the info gets polled. every poll = a fresh lil peek at what time it is ✨
  • format (string, default {:%H:%M}) — the format, aka how the date and time should be displayed. it's giving strftime energy. see the format options below for all the letters you can use 🌸
  • timezone (string) — the timezone to display the time in, e.g. America/New_York. an empty string "" represents the system's local timezone. there's a Wikipedia unofficial list of timezones at https://en.wikipedia.org/wiki/List_of_tz_database_time_zones if you need to find yours 💅
  • timezones (list of strings) — a list of timezones (same idea as timezone) to use for time display, and you flip between them with the scroll wheel 🖱️✨. do not specify the timezone option when timezones is specified, fr fr, pick one. and "" represents the system's local timezone
  • timezone-tooltip-format (string) — format to use for displaying timezones in the tooltip. when it's set, this lets you show timezone info (like timezone abbreviations) in the tooltip while keeping the main display clean 👑. uses the same format options as format
  • locale (string) — a locale to be used to display the time. intended to render times in custom timezones with the proper language and format 🌈
  • max-length (integer) — the maximum length in character the module should display (yes, "character", singular, that's literally what it says)
  • rotate (integer) — positive value to rotate the text label (in 90 degree increments). yes this is real and yes it slays 🔄
  • on-click (string) — command to execute when clicked on the module
  • on-click-middle (string) — command to execute when you middle clicked on the module using mousewheel
  • on-click-right (string) — command to execute when you right-click on the module
  • on-scroll-up (string) — command to execute when scrolling up on the module
  • on-scroll-down (string) — command to execute when scrolling down on the module
  • smooth-scrolling-threshold (double) — threshold to be used when scrolling
  • tooltip — bool, default true. Wanna have a lil tooltip pop up when you hover? Yeah you do. This turns it on/off. 🫶
  • tooltip-format — string, default is the same as format. This is the text that shows up in the hover tooltip, so you can make it different from the bar text itself. Obsessed with that flexibility ngl 💅
  • menu — string. The action that pops the menu open. 🎀
  • menu-file — string. Where your menu descriptor file lives. Heads up bestie, it needs to have a GtkMenu element with the id menu in there, or it's not gonna work. 💀
  • menu-actions — array. The actions that line up with the buttons of the menu. One per button, iykyk.
  • expand: — bool, default false. Lets this module gobble up all the leftover space dynamically. Main character energy fr, it eats the extra room 👑

Wanna see every valid format option? Peep strftime(3) or go stare at https://en.cppreference.com/w/cpp/chrono/duration/formatter ✨

🌸 2. Addressed by clock: calendar 🌸

This is the stuff for the calendar module, bestie 📅

  • mode — string, default month. The calendar view mode. Possible values: year|month 🗓️
  • mode-mon-col — integer, default 3. Only matters when mode=year. It's the count of months per row.
  • weeks-pos — string, no default. Where the week numbers should be displayed. It's disabled when it's empty. Possible values: left|right 💜
  • on-scroll — integer, default 1. The value to scroll months/years forward/backward by. Can be negative! And yes, it's configured under the on-scroll option 😭
  • iso8601 — bool, default false. When it's enabled, the calendar follows the ISO 8601 standard: weeks begin on Monday, and the first week of the year is numbered 1. The default week format is {:%V}. So iconic of it honestly 🌈

🎀 3. Addressed by clock: calendar: format 🎀

Formatting the calendar's little text bits, let's go ✨

  • months — string, no default. The format is applied to the months header (January, February,...etc.) 🍓
  • days — string, no default. The format is applied to days.
  • weeks — string, default {:%U}. The format is applied to week numbers. When the weekday format isn't provided, then the default format is used: {:%W} when the week starts with Monday, {:%U} otherwise. Yes bestie, that's two whole defaults doing different jobs, stay with me 💀
  • weekdays — string, no default. The format is applied to the weeks header (Su, Mo,...etc.) 🦋
  • today — string, default <b><u>{}</u></b>. The format is applied to Today. That default is literally bold + underlined, slay 💅

✨ Actions ✨

ok so these are the strings you can hand to actions (or to any of the click/scroll thingies) and here's literally what each one does 💅

  • mode — flips the calendar between year view and month view 🗓️
  • tz_up — jumps to the next timezone you provided
  • tz_down — jumps to the previously provided timezone
  • shift_up — moves to the next calendar month/year ⏭️
  • shift_down — moves to the previous calendar month/year ⏮️

🌈 FORMAT REPLACEMENTS 🌈

these little placeholder besties go in your format strings ✨

  • {calendar} — the current month calendar 🗓️
  • {tz_list} — a list of the time in the rest of the timezones, but only if you've set more than one timezone in the config
  • {ordinal_date} — today's date in (English) ordinal form, like 21st 🎀

💖 EXAMPLES 💖

1. General

"clock": {
     "interval": 60,
     "format": "{:%H:%M}",
     "max-length": 25
}

2. Calendar

"clock": {
     "format": "{:%H:%M}  ",
     "format-alt": "{:%A, %B %d, %Y (%R)}  ",
     "tooltip-format": "<tt><small>{calendar}</small></tt>",
     "calendar": {
          "mode"          : "year",
          "mode-mon-col"  : 3,
          "weeks-pos"     : "right",
          "on-scroll"     : 1,
          "on-click-right": "mode",
          "format": {
               "months":     "<span color='#ffead3'><b>{}</b></span>",
               "days":       "<span color='#ecc6d9'><b>{}</b></span>",
               "weeks":      "<span color='#99ffdd'><b>W{}</b></span>",
               "weekdays":   "<span color='#ffcc66'><b>{}</b></span>",
               "today":      "<span color='#ff6699'><b><u>{}</u></b></span>"
          }
     },
     "actions": {
          "on-click-right": "mode",
          "on-click-forward": "tz_up",
          "on-click-backward": "tz_down",
          "on-scroll-up": "shift_up",
          "on-scroll-down": "shift_down"
     }
},

3. Full date on hover

"clock": {
     "interval": 60,
     "tooltip": true,
     "format": "{:%H.%M}",
     "tooltip-format": "{:%Y-%m-%d}",
}

4. Show timezone in tooltip only

"clock": {
     "interval": 60,
     "format": "{:%H:%M}",
     "timezone-tooltip-format": "{:%H:%M %Z}",
     "timezones": [
          "",
          "America/Chicago",
          "America/Los_Angeles",
          "Europe/Paris",
          "UTC"
     ],
     "tooltip": true,
     "tooltip-format": "{tz_list}"
}

🎀 STYLE 🎀

  • #clock

🩺 Troubleshooting

so like… if your clock module just refuses to show up at startup and throws a locale::facet::_S_create_c_locale / name not valid error message at you 😭 then try one of these bestie:

  • check that LC_TIME is set properly (that's the glibc route)
  • set the locale to C in the config file (that's the musl route)
heads up!! the locale option must be set for {calendar} to use the correct start-of-week, no matter what your system locale says. no cap. 👑

🌸 Calendar in Chinese. Alignment 🌸

if you want a Chinese calendar that's actually aligned and not giving chaos, here are some genuinely useful recommendations 🫶

  1. use "WenQuanYi Zen Hei Mono" — it ships with most Linux distributions, iconic of them honestly
  2. try different font sizes and find the best one for you. size = 9pt should be fine ✨
  3. if "WenQuanYi Zen Hei Mono" is the font you're using, disable the monospace font pango tag

Example of working config 💜

"clock": {
     "format": "{:%H:%M}  ",
     "format-alt": "{:%A, %B %d, %Y (%R)}  ",
     "tooltip-format": "n<span size='9pt' font='WenQuanYi Zen Hei Mono'>{calendar}</span>",
     "calendar": {
          "mode"          : "year",
          "mode-mon-col"  : 3,
          "weeks-pos"     : "right",
          "on-scroll"     : 1,
          "on-click-right": "mode",
          "format": {
               "months":     "<span color='#ffead3'><b>{}</b></span>",
               "days":       "<span color='#ecc6d9'><b>{}</b></span>",
               "weeks":      "<span color='#99ffdd'><b>W{}</b></span>",
               "weekdays":   "<span color='#ffcc66'><b>{}</b></span>",
               "today":      "<span color='#ff6699'><b><u>{}</u></b></span>"
          }
     },
     "actions": {
          "on-click-right": "mode",
          "on-click-forward": "tz_up",
          "on-click-backward": "tz_down",
          "on-scroll-up": "shift_up",
          "on-scroll-down": "shift_down"
     }
},

👑 AUTHOR 👑

Alexis Rouillard <contact@arouillard.fr> — absolute legend, we stan 🫶

and that's the whole page bestie!! you made it to the end 🎉 this is waybar-clock, page waybar-clock(5), dated 2026-02-08 — go forth and make your bar adorable, you got this fr fr 💖✨🦋

📦 where this page comes from