Skip to content

feat: render 12/24 hour format according to user's preference and add hourCycle option #329

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
silverwind wants to merge 11 commits into
base: main
Choose a base branch
from
Open

feat: render 12/24 hour format according to user's preference and add hourCycle option #329

Show file tree
Hide file tree
Changes from 10 commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
e3a6c33
Render 12/24 hour format according to user's preference
silverwind Oct 27, 2025
2942825
format
silverwind Oct 27, 2025
85a9943
prefer RegExp.prototype.exec
silverwind Oct 28, 2025
96cb9c5
update comment
silverwind Oct 28, 2025
b2e15aa
add override option
silverwind Oct 28, 2025
e52f34b
use correct h23
silverwind Oct 28, 2025
343328c
add isHour12 function to support h11
silverwind Oct 28, 2025
2db2686
revert script
silverwind Oct 28, 2025
a2d1259
use documented argument for format
silverwind Oct 28, 2025
f5dd512
Add hour-cycle to observedAttributes and add tests
silverwind Feb 14, 2026
0f48a5e
Address review comments
silverwind Feb 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 21 additions & 20 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,26 +56,27 @@ So, a relative date phrase is used for up to a month and then the actual date is

#### Attributes

| Property Name | Attribute Name | Possible Values | Default Value |
| :------------- | :--------------- | :------------------------------------------------------------------------------------------ | :------------------------ |
| `datetime` | `datetime` | `string` | - |
| `format` | `format` | `'datetime'\|'relative'\|'duration'` | `'auto'` |
| `date` | - | `Date \| null` | - |
| `tense` | `tense` | `'auto'\|'past'\|'future'` | `'auto'` |
| `precision` | `precision` | `'year'\|'month'\|'day'\|'hour'\|'minute'\|'second'` | `'second'` |
| `threshold` | `threshold` | `string` | `'P30D'` |
| `prefix` | `prefix` | `string` | `'on'` |
| `formatStyle` | `format-style` | `'long'\|'short'\|'narrow'` | <sup>\*</sup> |
| `second` | `second` | `'numeric'\|'2-digit'\|undefined` | `undefined` |
| `minute` | `minute` | `'numeric'\|'2-digit'\|undefined` | `undefined` |
| `hour` | `hour` | `'numeric'\|'2-digit'\|undefined` | `undefined` |
| `weekday` | `weekday` | `'short'\|'long'\|'narrow'\|undefined` | <sup>\*\*</sup> |
| `day` | `day` | `'numeric'\|'2-digit'\|undefined` | `'numeric'` |
| `month` | `month` | `'numeric'\|'2-digit'\|'short'\|'long'\|'narrow'\|undefined` | <sup>\*\*\*</sup> |
| `year` | `year` | `'numeric'\|'2-digit'\|undefined` | <sup>\*\*\*\*</sup> |
| `timeZoneName` | `time-zone-name` | `'long'\|'short'\|'shortOffset'\|'longOffset'` `\|'shortGeneric'\|'longGeneric'\|undefined` | `undefined` |
| `timeZone` | `time-zone` | `string\|undefined` | Browser default time zone |
| `noTitle` | `no-title` | `-` | `-` |
| Property Name | Attribute Name | Possible Values | Default Value |
| :------------- | :--------------- | :------------------------------------------------------------------------------------------ | :------------------------------- |
| `datetime` | `datetime` | `string` | - |
| `format` | `format` | `'datetime'\|'relative'\|'duration'` | `'auto'` |
| `date` | - | `Date \| null` | - |
| `tense` | `tense` | `'auto'\|'past'\|'future'` | `'auto'` |
| `precision` | `precision` | `'year'\|'month'\|'day'\|'hour'\|'minute'\|'second'` | `'second'` |
| `threshold` | `threshold` | `string` | `'P30D'` |
| `prefix` | `prefix` | `string` | `'on'` |
| `formatStyle` | `format-style` | `'long'\|'short'\|'narrow'` | <sup>\*</sup> |
| `second` | `second` | `'numeric'\|'2-digit'\|undefined` | `undefined` |
| `minute` | `minute` | `'numeric'\|'2-digit'\|undefined` | `undefined` |
| `hour` | `hour` | `'numeric'\|'2-digit'\|undefined` | `undefined` |
| `weekday` | `weekday` | `'short'\|'long'\|'narrow'\|undefined` | <sup>\*\*</sup> |
| `day` | `day` | `'numeric'\|'2-digit'\|undefined` | `'numeric'` |
| `month` | `month` | `'numeric'\|'2-digit'\|'short'\|'long'\|'narrow'\|undefined` | <sup>\*\*\*</sup> |
| `year` | `year` | `'numeric'\|'2-digit'\|undefined` | <sup>\*\*\*\*</sup> |
| `timeZoneName` | `time-zone-name` | `'long'\|'short'\|'shortOffset'\|'longOffset'` `\|'shortGeneric'\|'longGeneric'\|undefined` | `undefined` |
| `timeZone` | `time-zone` | `string\|undefined` | Browser default time zone |
| `hourCycle` | `hour-cycle` | `'h11'\|'h12'\|'h23'\|'h24'\|undefined` | 'h12' or 'h23' based on browser |
| `noTitle` | `no-title` | `-` | `-` |

<sup>\*</sup>: If unspecified, `formatStyle` will return `'narrow'` if `format` is `'elapsed'` or `'micro'`, `'short'` if the format is `'relative'` or `'datetime'`, otherwise it will be `'long'`.

Expand Down
14 changes: 14 additions & 0 deletions examples/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,20 @@ <h3>Format DateTime</h3>
</relative-time>
</p>

<p>
h12 cycle:
<relative-time datetime="1970-01-01T00:00:00.000Z" format="datetime" hour="numeric" minute="2-digit" second="2-digit" hour-cycle="h12">
Jan 1 1970
</relative-time>
</p>

<p>
h23 cycle:
<relative-time datetime="1970-01-01T00:00:00.000Z" format="datetime" hour="numeric" minute="2-digit" second="2-digit" hour-cycle="h23">
Jan 1 1970
</relative-time>
</p>

<p>
Customised options:
<relative-time datetime="1970-01-01T00:00:00.000Z" format="datetime" weekday="narrow" year="2-digit" month="narrow" day="numeric" hour="numeric" minute="2-digit" second="2-digit">
Expand Down
24 changes: 24 additions & 0 deletions src/relative-time-element.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,18 @@ function getUnitFactor(el: RelativeTimeElement): number {
return 60 * 60 * 1000
}

// Determine whether the user has a 12 (vs. 24) hour cycle preference. This relies on the hour formatting in
// a 12 hour preference being formatted like "1 AM" including a space, while with a 24 hour preference, the
// same is formatted as "01" without a space. In the future `Intl.Locale.prototype.getHourCycles()` could be
// used but it is not as well-supported as this method.
function isBrowser12hCycle() {
return Boolean(/\s/.exec(new Intl.DateTimeFormat([], {hour: 'numeric'}).format(new Date(0))))
}

function isHour12(hourCycle: Intl.DateTimeFormatOptions['hourCycle']) {
return hourCycle === 'h11' || hourCycle === 'h12'
}

const dateObserver = new (class {
elements: Set<RelativeTimeElement> = new Set()
time = Infinity
Expand Down Expand Up @@ -98,6 +110,14 @@ export class RelativeTimeElement extends HTMLElement implements Intl.DateTimeFor
return tz || undefined
}

get hourCycle() {
// Prefer attribute, then closest, then document
const hc =
this.closest('[hour-cycle]')?.getAttribute('hour-cycle') ||
this.ownerDocument.documentElement.getAttribute('hour-cycle')
return (hc || (isBrowser12hCycle() ? 'h12' : 'h23')) as Intl.DateTimeFormatOptions['hourCycle']
}

#renderRoot: Node = this.shadowRoot ? this.shadowRoot : this.attachShadow ? this.attachShadow({mode: 'open'}) : this

static get observedAttributes() {
Expand All @@ -122,6 +142,7 @@ export class RelativeTimeElement extends HTMLElement implements Intl.DateTimeFor
'title',
'aria-hidden',
'time-zone',
'hour-cycle',
]
}

Expand All @@ -139,6 +160,7 @@ export class RelativeTimeElement extends HTMLElement implements Intl.DateTimeFor
minute: '2-digit',
timeZoneName: 'short',
timeZone: this.timeZone,
hour12: isHour12(this.hourCycle),
}).format(date)
}

Expand Down Expand Up @@ -213,6 +235,7 @@ export class RelativeTimeElement extends HTMLElement implements Intl.DateTimeFor
year: this.year,
timeZoneName: this.timeZoneName,
timeZone: this.timeZone,
hour12: isHour12(this.hourCycle),
})
return `${this.prefix} ${formatter.format(date)}`.trim()
}
Expand Down Expand Up @@ -246,6 +269,7 @@ export class RelativeTimeElement extends HTMLElement implements Intl.DateTimeFor
minute: '2-digit',
timeZoneName: 'short',
timeZone: this.timeZone,
hour12: isHour12(this.hourCycle),
}

if (this.#isToday(date)) {
Expand Down
129 changes: 129 additions & 0 deletions test/relative-time.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1982,6 +1982,7 @@ suite('relative-time', function () {
const el = document.createElement('relative-time')
el.setAttribute('lang', 'es-ES')
el.setAttribute('time-zone', 'Europe/Madrid')
el.setAttribute('hour-cycle', 'h23')

el.setAttribute('datetime', '2023-01-15T17:00:00.000Z')
await Promise.resolve()
Expand Down Expand Up @@ -2815,6 +2816,134 @@ suite('relative-time', function () {
}
})

suite('[hourCycle]', function () {
test('formats with 24-hour cycle when hour-cycle is h23', async () => {
const el = document.createElement('relative-time')
el.setAttribute('datetime', '2020-01-01T15:00:00.000Z')
el.setAttribute('time-zone', 'UTC')
el.setAttribute('format', 'datetime')
el.setAttribute('hour', 'numeric')
el.setAttribute('minute', '2-digit')
el.setAttribute('hour-cycle', 'h23')
await Promise.resolve()
assert.notMatch(el.shadowRoot.textContent, /AM|PM/i)
assert.match(el.shadowRoot.textContent, /15:00/)
})

test('formats with 12-hour cycle when hour-cycle is h12', async () => {
const el = document.createElement('relative-time')
el.setAttribute('datetime', '2020-01-01T15:00:00.000Z')
el.setAttribute('time-zone', 'UTC')
el.setAttribute('format', 'datetime')
el.setAttribute('hour', 'numeric')
el.setAttribute('minute', '2-digit')
el.setAttribute('hour-cycle', 'h12')
await Promise.resolve()
assert.match(el.shadowRoot.textContent, /3:00/)
assert.match(el.shadowRoot.textContent, /PM/i)
})

test('formats with 12-hour cycle when hour-cycle is h11', async () => {
const el = document.createElement('relative-time')
el.setAttribute('datetime', '2020-01-01T15:00:00.000Z')
el.setAttribute('time-zone', 'UTC')
el.setAttribute('format', 'datetime')
el.setAttribute('hour', 'numeric')
el.setAttribute('minute', '2-digit')
el.setAttribute('hour-cycle', 'h11')
await Promise.resolve()
assert.match(el.shadowRoot.textContent, /3:00/)
assert.match(el.shadowRoot.textContent, /PM/i)
})

test('formats with 24-hour cycle when hour-cycle is h24', async () => {
const el = document.createElement('relative-time')
el.setAttribute('datetime', '2020-01-01T15:00:00.000Z')
el.setAttribute('time-zone', 'UTC')
el.setAttribute('format', 'datetime')
el.setAttribute('hour', 'numeric')
el.setAttribute('minute', '2-digit')
el.setAttribute('hour-cycle', 'h24')
await Promise.resolve()
assert.notMatch(el.shadowRoot.textContent, /AM|PM/i)
})

test('title uses hour-cycle setting', async () => {
const el = document.createElement('relative-time')
el.setAttribute('datetime', '2020-01-01T15:00:00.000Z')
el.setAttribute('time-zone', 'UTC')
el.setAttribute('hour-cycle', 'h23')
await Promise.resolve()
assert.notMatch(el.getAttribute('title'), /AM|PM/i)
assert.match(el.getAttribute('title'), /15/)
})

test('inherits hour-cycle from ancestor', async () => {
const el = document.createElement('relative-time')
el.setAttribute('datetime', '2020-01-01T15:00:00.000Z')
el.setAttribute('time-zone', 'UTC')
el.setAttribute('format', 'datetime')
el.setAttribute('hour', 'numeric')
el.setAttribute('minute', '2-digit')
const div = document.createElement('div')
div.setAttribute('hour-cycle', 'h23')
div.appendChild(el)
document.body.appendChild(div)
await Promise.resolve()
assert.notMatch(el.shadowRoot.textContent, /AM|PM/i)
assert.match(el.shadowRoot.textContent, /15:00/)
div.remove()
})

test('inherits hour-cycle from documentElement', async () => {
const el = document.createElement('relative-time')
el.setAttribute('datetime', '2020-01-01T15:00:00.000Z')
el.setAttribute('time-zone', 'UTC')
el.setAttribute('format', 'datetime')
el.setAttribute('hour', 'numeric')
el.setAttribute('minute', '2-digit')
document.documentElement.setAttribute('hour-cycle', 'h23')
await Promise.resolve()
assert.notMatch(el.shadowRoot.textContent, /AM|PM/i)
assert.match(el.shadowRoot.textContent, /15:00/)
document.documentElement.removeAttribute('hour-cycle')
})

test('element attribute overrides ancestor', async () => {
const el = document.createElement('relative-time')
el.setAttribute('datetime', '2020-01-01T15:00:00.000Z')
el.setAttribute('time-zone', 'UTC')
el.setAttribute('format', 'datetime')
el.setAttribute('hour', 'numeric')
el.setAttribute('minute', '2-digit')
el.setAttribute('hour-cycle', 'h12')
const div = document.createElement('div')
div.setAttribute('hour-cycle', 'h23')
div.appendChild(el)
document.body.appendChild(div)
await Promise.resolve()
assert.match(el.shadowRoot.textContent, /3:00/)
assert.match(el.shadowRoot.textContent, /PM/i)
div.remove()
})

test('re-renders when hour-cycle attribute changes', async () => {
const el = document.createElement('relative-time')
el.setAttribute('datetime', '2020-01-01T15:00:00.000Z')
el.setAttribute('time-zone', 'UTC')
el.setAttribute('format', 'datetime')
el.setAttribute('hour', 'numeric')
el.setAttribute('minute', '2-digit')
el.setAttribute('hour-cycle', 'h12')
await Promise.resolve()
assert.match(el.shadowRoot.textContent, /PM/i)
el.setAttribute('hour-cycle', 'h23')
await Promise.resolve()
assert.notMatch(el.shadowRoot.textContent, /AM|PM/i)
assert.match(el.shadowRoot.textContent, /15:00/)
})
})

suite('[timeZone]', function () {
test('updates when the time-zone attribute is set', async () => {
const el = document.createElement('relative-time')
Expand Down
Loading