@duskmoon-dev/el-datetime
A display-only Web Component that formats ISO dates and datetimes as semantic <time>
content.
Installation
bun add @duskmoon-dev/el-datetime
Registration
import '@duskmoon-dev/el-datetime/register';
Or register it explicitly:
import { register } from '@duskmoon-dev/el-datetime';
register();
Usage
<el-dm-datetime
value="2026-08-11T14:30:45Z"
format="YYYY-MM-DD HH:mm:ss"
time-zone="Asia/Shanghai"
></el-dm-datetime>
The example renders 2026-08-11 22:30:45 while retaining the original value in the
inner <time datetime="..."> attribute.
Attributes
| Attribute | Type | Default | Description |
|---|---|---|---|
value | string | '' | ISO date or datetime to display |
format | string | 'YYYY-MM-DD HH:mm' | Output format |
time-zone | string | '' | IANA time zone for timestamps with Z or an offset; empty uses the browser time zone |
Format tokens
| Token | Output |
|---|---|
YYYY, YY | Four- or two-digit year |
M, MM | Month without or with zero-padding |
D, DD | Day without or with zero-padding |
H, HH | 24-hour time without or with zero-padding |
h, hh | 12-hour time without or with zero-padding |
m, mm | Minutes without or with zero-padding |
s, ss | Seconds without or with zero-padding |
SSS | Milliseconds |
A, a | Upper- or lowercase meridiem |
Wrap literal text in brackets so token letters are not interpreted:
<el-dm-datetime value="2026-08-11T14:30:45" format="YYYY-MM-DD [at] h:mm A"></el-dm-datetime>
This renders 2026-08-11 at 2:30 PM.
Input and time-zone behavior
- Accepted values are
YYYY-MM-DDand ISO datetimes such as2026-08-11T14:30,2026-08-11T14:30:45.123456Z, or2026-08-11T14:30:45+08:00. Fractional seconds are truncated to milliseconds for theSSStoken. - Date-only and offsetless datetime values are wall-clock values and are not shifted by
time-zone. - Values with
Zor an explicit offset represent an instant. They are converted totime-zone, or to the browser's local time zone when the attribute is omitted. - Invalid values, impossible dates, and invalid time zones render empty content without throwing.
Use an explicit Z or offset whenever time-zone conversion matters.
CSS parts
| Part | Description |
|---|---|
time | The semantic <time> element |