[css-values] Time based numerical functions

[johannesodland]

Splitting off from #13655.

Using the current time can be useful for creating dynamic computed themes and layouts.
To avoid flashes of wrongly styled content, this is currently only possible by adding blocking scripts to set a custom property or attribute.

Proposal

Add time functions that return <number> values:

• year()
• month()
• day()
• day-of-week()
• day-of-year()
• weak-of-year()
• ...

The time functions should roughly match the Temporal ZonedDateTime properties to make it easier to learn.

To provide values specific to one time zone or calendar, the functions could optionally accept time zone and calendar as a parameter:

day-of-year("Europe/Brussels" iso8601)

To provide values specific to one zoned date time, the functions could optionally accept a RFC 9557 string:

day-of-year("2026-03-15T11:00:00+01:00[Europe/Oslo]")

Use cases

1. Time based theming

A mini-game is set up to have a generative color theme based on the day of the year. Each day the game has a new combination of colors.

--background-color-1: ...;
--background-color-2: ...;
--background-color-3: ...;
--background-index: mod(day-of-year(), 3);


background-color: var(ident("--background-color-" var(--background-index)));

2. Highlighting simple timetables

A local hackerspace has a time table with the daily opening hours and the person responsible.
day-of-week() could be used in a style query to highlight the row corresponding to the current week day,
although conditional time queries as discussed in #9710 could be better for this purpose if supported.

<table>
  <tr data-timetable-day=1>...</tr>
  <tr data-timetable-day=2>...</tr>
</table>

--timetable-day: attr("data-timetable-day" type(<number>));

font-weight: if(
  style(--timetable-day: day-of-week()): bold;
  else: normal;
);

Related proposals

• [mediaqueries] Dates #9710
• [css-animations][web-animations] Animations based on absolute/wall time #13664

[ydaniv]

Do you expect these values to update every second? These will probably cause style recalculation every second 🤔

[SebastianZ]

I'd expect it to only update on changes, e.g. for day-of-year() once the day changes.

Sebastian

[Crissov]

Why would these be functions instead of environment variables accessible by env()?

Could a single function like current(<CLDR-datetime>) be more useful? Why would I ever want to style depending on any date and time other than now?

How do you get the current month number of, for instance, the Hebrew, Islamic or Coptic calendar?

What would the function for the day of the week (DOW) return today, i.e. on a Sunday? Does it differ if I was from (or in) the US or Afghanistan instead of Europe?

Which number does the year function return when my browser/OS locale is set to Thailand, Japan, Ethiopia or Iran?

How do I use these functions to style something for Lent, Orthodox Easter, Ramadan, US Thanksgiving, Chinese New Year, Pisces or Mother’s Day?

Does the day function always change its result at local midnight or can I get it to switch at dusk, nightfall, sunset (at a specific place), 06:00 or noon?

[johannesodland]

Why would these be functions instead of environment variables accessible by env()?

I think that would prevent us from specifying time relative to a specific time zone or calendar.

--background-index: mod(day-of-year("Europe/Brussels"), 3);

Could a single function like current(<CLDR-datetime>) be more useful? Why would I ever want to style depending on any date and time other than now?

I'm not sure I quite understand.
This proposal is for numeric functions for use in computed theming / layout. We need specific functions depending on whether we want to use day-of-year or week-of-year or month in our calculations.

I think most conditional styling is better solved with a conditional time query like you proposed in #9710. Something like @media time(2023-11-20 <= current <= 2023-11-26). Let's discuss that over there :)

I'll edit my proposal text to make it more clear that this is for use in computations (and not conditional css) i.e. calculating a theme color based on the numeric value returned from the function (or keyword).

How do you get the current month number of, for instance, the Hebrew, Islamic or Coptic calendar?

What would the function for the day of the week (DOW) return today, i.e. on a Sunday? Does it differ if I was from (or in) the US or Afghanistan instead of Europe?

Which number does the year function return when my browser/OS locale is set to Thailand, Japan, Ethiopia or Iran?

I think it should be aligned with the corresponding Temporal property:

month:
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime/month
https://tc39.es/proposal-temporal/docs/zoneddatetime.html#month

dayOfWeek:
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime/dayOfWeek

year:
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime/year

How do I use these functions to style something for Lent, Orthodox Easter, Ramadan, US Thanksgiving, Chinese New Year, Pisces or Mother’s Day?

They are not designed to solve that problem. I think conditional time queries could be better suited for that. Let's discuss over in #9710.

Does the day function always change its result at local midnight or can I get it to switch at dusk, nightfall, sunset (at a specific place), 06:00 or noon?

Maybe the functions could accept an hourly offset like day-of-year(+8)? It would be possible to use another timezone, but then different daylight saving times might apply.