Repository navigation
BLL Date
Method reference · time · number · Examples
date formats a calendar date or clock time. It returns text, using the
configured BLL locale and Homey's time zone unless the caller or expression
supplies overrides. In a supported text field:
Today is {[ date("dddd") ]}.
In an expression-only card, enter date("dddd") without {[ ]}.
date(format)
date(format, dateValue, locale, timeZone)
date(format, locale, timeZone)The last form uses the current date and a recognized locale tag, for example
date("dddd", "nl", "Europe/Amsterdam"). The second form accepts a date
string with an offset, a Date, or a Unix timestamp in milliseconds.
Pass null as dateValue when you want the current time with explicit
locale and time zone in the four-argument form. Use an IANA time-zone name
such as Europe/Amsterdam or UTC.
For reliable results, prefer ISO 8601 strings with Z or an explicit offset.
Ambiguous local date strings can be interpreted differently. In the 4.2.3
source, a numeric zero date is treated as absent; do not rely on date(..., 0)
to format the Unix epoch. Explicit overrides and custom formats can also
interact; preview the result in your installed version.
The format argument accepts the built-in names and tokens below. Codes are
case-sensitive; the differently-cased aliases listed here are separate
supported codes. Locale and time zone can change the resulting text. Unless
noted, the example outputs use locale en-US, the instant
2026-11-12T13:08:09.123Z and time zone Europe/Amsterdam.
These names select locale-aware Intl styles. Both the codes listed in
App settings → Formats and the aliases shown here are accepted. Results
show the built-in formats before any settings override.
| Output | Style | Accepted format codes | Example result (en-US) |
|---|---|---|---|
| Date and time | Full |
DATETIMELONG, datetimelong, LONGDATETIME, longdatetime
|
Thursday, November 12, 2026 at 2:08:09 PM Central European Standard Time |
| Date and time | Long | DATETIME |
November 12, 2026 at 2:08:09 PM GMT+1 |
| Date and time | Medium | datetime |
Nov 12, 2026, 2:08:09 PM |
| Date and time | Short |
datetimeshort, shortdatetime
|
11/12/26, 2:08 PM |
| Date | Full |
DATELONG, datelong, LONGDATE, longdate
|
Thursday, November 12, 2026 |
| Date | Long | DATE |
November 12, 2026 |
| Date | Medium | date |
Nov 12, 2026 |
| Date | Short |
dateshort, shortdate
|
11/12/26 |
| Time | Full |
TIMELONG, timelong, LONGTIME, longtime
|
2:08:09 PM Central European Standard Time |
| Time | Long | TIME |
2:08:09 PM GMT+1 |
| Time | Medium | time |
2:08:09 PM |
| Time | Short |
timeshort, shorttime
|
2:08 PM |
Use the longer tokens where one token starts with another, such as MMMM
before MM or HH24 before HH.
| Tokens | Meaning | Example result (en-US) |
|---|---|---|
yyyy, yy
|
Four-digit or two-digit year |
2026, 26
|
MMMM, MMM, MM, M
|
Full month name, abbreviated month name, two-digit month, numeric month |
November, Nov, 11, 11
|
dddd, ddd
|
Full or abbreviated weekday name |
Thursday, Thu
|
dd, d
|
Two-digit or numeric day of month |
12, 12
|
HH, H
|
24-hour clock, with leading zero or without |
14, 14
|
HH24, H24
|
24-hour-cycle clock using the 1–24 cycle (midnight can be 24) |
14, 14
|
hh, h
|
12-hour clock, with leading zero or without |
02, 2
|
tt |
Locale-specific AM/PM marker | PM |
mm, m
|
Two-digit or numeric minute |
08, 8
|
ss, s
|
Two-digit or numeric second |
09, 9
|
fff, ff, f
|
Millisecond fraction with three, two or one digits |
123, 12, 1
|
| Tokens | Meaning | Example result (en-US) |
|---|---|---|
PERIOD, period
|
Locale-specific day-period text, in long or short form (for example, morning or afternoon) | in the afternoon |
ERA, era
|
Locale-specific era name, in long or short form |
Anno Domini, AD
|
KK, kk
|
Long or short localized time-zone name |
Central European Standard Time, GMT+1
|
z, zz
|
Numeric time-zone offset, with one- or two-character hour width |
+1, +01
|
Z, ZZ
|
Numeric time-zone offset prefixed with GMT, with one- or two-character hour width |
GMT+1, GMT+01
|
ISO |
UTC ISO timestamp | 2026-11-12T13:08:09.123Z |
ISOZ |
ISO-like date and time with the configured time-zone offset | 2026-11-12T14:08:09.123+01:00 |
PERIOD and period are distinct from tt: the former return a localized
day-period phrase, while tt returns the locale's AM/PM marker. Day-period
and era text depend on locale and date. The numeric z, zz, Z and ZZ
forms are legacy offset formats; check their output in the settings preview,
especially for time zones whose offsets include minutes.
In the 4.2.3 implementation, ERA removes the host's current UTC year from
the formatted result; the Anno Domini example assumes the host year is
2026. A different year may remain in the output.
For example, these expressions return the current localized day period in long and short styles:
{[ date("PERIOD") ]}
{[ date("period") ]}
Text inside double quotes is copied literally into the result. For example:
{[ date('yyyy-MM-dd "at" HH:mm') ]}
Use "" inside a format to output a literal double quote. In App settings →
Formats, you can change built-in formats or add a named custom format, then
use that name as the date format argument. Preview custom formats before
using them; changing a built-in format can affect other apps that use it.
The following code-reference images are from the BLL users topic, post 3. They show examples for the locale used at the time and may differ from your app version and settings. Some codes in the historical screenshots have changed; use the current code table above rather than assuming the screenshots match your installed version.
Historical format-reference screenshot, part one; use the current table above for supported tokens and examples.
Historical format-reference screenshot, part two; labels and defaults may differ from the current app.
Historical format-reference screenshot, part three; verify any code against the current reference above.
Each row is a bare expression for an expression card. Wrap it in
{[ ... ]} to use it inside supported text. Unless otherwise stated, the
fixed input below is 12 November 2026 at 13:08:09.123 UTC.
| Expression | Example output |
|---|---|
date("yyyy-MM-dd", "2026-11-12T13:08:09.123Z", "en-GB", "UTC") |
2026-11-12 |
date("dd/MM/yyyy", "2026-11-12T13:08:09.123Z", "en-GB", "UTC") |
12/11/2026 |
date("dddd, d MMMM yyyy", "2026-11-12T13:08:09.123Z", "en-GB", "UTC") |
Thursday, 12 November 2026 |
date("HH:mm:ss", "2026-11-12T13:08:09.123Z", "en-GB", "UTC") |
13:08:09 |
date("hh:mm tt", "2026-11-12T13:08:09.123Z", "en-US", "UTC") |
01:08 PM |
date("HH:mm", "2026-11-12T13:08:09.123Z", "en-GB", "Europe/Amsterdam") |
14:08 |
date("HH:mm", "2026-11-12T13:08:09.123Z", "en-GB", "America/New_York") |
08:08 |
date("ISO", "2026-11-12T13:08:09.123Z", "en-GB", "UTC") |
2026-11-12T13:08:09.123Z |
The same instant can have a different date in another time zone. Date and language conventions may also change across Homey/runtime versions.
| Supported text | What it produces |
|---|---|
The time is {[ date("HH:mm") ]} |
Current local clock time. |
Tomorrow at this instant: {[ date("yyyy-MM-dd HH:mm", now + 86400000) ]} |
The instant 24 hours from now. |
In 90 minutes: {[ date("shorttime", now + 90 * 60000) ]} |
Clock time 90 minutes from now. |
Timestamp: {[ now ]} |
Current Unix time in milliseconds. |
Seconds: {[ Math.floor(now / 1000) ]} |
Current Unix time in seconds. |
now is set once per expression evaluation. A period of 24 hours is not
always the next local calendar day across daylight-saving transitions.
In App settings → Formats, add a custom name such as ReportDate and
set its definition to yyyy-MM-dd. Save it, then use
{[ date("ReportDate") ]}. The settings page previews the output. Existing
default formats can also be changed, affecting other apps using BLL date
formats. Choose unique names and test before changing shared definitions.
Literal text in a format can be enclosed in double quotes, for example:
{[ date('yyyy-MM-dd "at" HH:mm') ]}
The quotes around at are part of the format; the outer single quotes are
JavaScript string delimiters.
Support development - If Better Logic Library is useful to you, you can support its
continued development through GitHub Sponsors,
Patreon,
PayPal, or
bunq.
Thank you!


