feat (clock): Add support for optional CSS classes to the clock module's calendar tooltip

[nickjj]

NOTE: I've never written a line of C++ in my life. I used a combination of looking at the existing source code and Google's ask AI. I'd like to think this isn't pure AI slop as I thought through the problem and scope of the problem ahead of time. I only used AI to help me understand the C++ syntax. The diff is pretty small.

This fixes #3686 and addresses #4787.

Feature

The clock's calendar doesn't support CSS classes. To customize its colors you typically have to do:

      "format": {
        "months": "<span color='#ffead3'><b>{}</b></span>",
        "days": "<span color='#ecc6d9'><b>{}</b></span>",
        "weeks": "<span color='#99ffdd'><b>W{:%V}</b></span>",
        "weekdays": "<span color='#ffcc66'><b>{}</b></span>",
        "today": "<span color='#ff6699'><b><u>{}</u></b></span>"
      }

Waybar itself exposes CSS based styling. Having hard coded hex colors in the JSON config makes it tedious to theme Waybar's clock module since you'd have to update the JSON file instead of the CSS file. This is problematic if you have your dotfiles in version control where inline edits create git diffs.

It is IMO cleaner if you can do:

      "format": {
        "months": "<span class='months'>{}</span>",
        "days": "<span class='days'>{}</span>",
        "weeks": "<span class='weeks'>W{:%V}</span>",
        "weekdays": "<span class='weekdays'>{}</span>",
        "today": "<span class='today'>{}</span>"
      }

And now in your CSS file you can do:

#clock.calendar-today { color: #ff0000; }
#clock.calendar-days { color: #00ff00; }
#clock.calendar-weeks { color: #0000ff; }
#clock.calendar-weekdays { color: #fff000; }
#clock.calendar-months { color: #ff00ff; }

This lets you extract the above into CSS variables in a theme specific file and now you can symlink your active theme.

Backwards and forwards compatibility

I tried to be mindful of both scenarios.

I wanted to keep the original implementation as close as possible so I went for a "post processing" approach which uses a string find / replace.

• If you want to continue using the original way to style the tooltip that works fine
• If you want to use the new way with CSS classes, this also works
• If you want to combine both, this also works

If in the future someone overhauls Waybar or this module to have proper CSS support, end users won't have to modify their class based approach to have that continue working.

Manual tests

The following works:

• 6 char hex codes
• 3 char hex codes
• Valid CSS color names (ie. "silver")
• Invalid CSS throws a descriptive error
  • When setting #clock.calendar-today { color: maze; }:
    • [2026-03-02 20:09:07.523] [error] style.css:73:35'maze' is not a valid color name
  • When setting #clock.calendar-today { hello: world; }:
    • [2026-03-02 20:10:09.736] [error] style.css:73:30'hello' is not a valid property name

Limitations

Hot reloading

For hot reloading the CSS without needing to restart Waybar, the clock itself has to update in some way such as the time changing or performing one of the mouse actions.

I tried slamming my head at this problem for a bit but I don't know enough about C++ to solve this. If anyone has any suggestions please let me know. I don't think this is a show stopper but if it's easy to add this behavior, that would be nice!

Limited CSS options

Secondly, not all CSS is supported since I didn't use a CSS parser. Behind the scenes it simply turns class= into color= and ensures a 6 digit hex code is provided for the color so Pango is happy. You can still use Pango supported syntax like <b> in your JSON file.

This isn't ideal but it's a first step and likely solves the 95% case of folks wanting to use custom CSS colors.

Given this limitation I didn't document this new behavior in the man entry. My thought process is the world survived for years without this feature and if you care enough about theming this calendar you'll find this PR or figure it out through experimentation. What do you think, is it worth documenting as is?

Alternative strategy

If using a "fake" class= is too misleading maybe we can overload color= and if instead of a color being passed in, if someone passes in @today it will look for a calendar-today class in your stylesheet and get that value. This way the intent is a little more clear that it only supports colors and not all CSS properties. Using @ was chosen because it's how you reference CSS variables. It at least has a mental model to that.

[nickjj]

@Alexays sorry for the ping but any chance this can get reviewed? I'd like to retire my custom fork of Waybar if we can get this merged. It solves quite a few open issues and is a quality of life win for folks who want to theme Waybar's clock.