intlDateTime - Intl by Before Semicolon

`intlDateTime`

intlDateTime(value, options?) formats a date-like value as localized date/time text. Use this for values you already have in JS and want the same output as <intl-datetime>.

It uses the same option model as: Intl.DateTimeFormat and uses the same runtime locale resolution as components.

Native output context: HTML ``.

Input shape

value can be:

Date
timestamp number (ms since epoch)
ISO/string date ('2026-01-01T10:00:00Z')

1import { intlDateTime } from '@beforesemicolon/intl'2 3intlDateTime('2026-01-01T10:00:00Z')4intlDateTime(1704067200000)5intlDateTime(new Date('2026-01-01T10:00:00Z'))

Signature

1function intlDateTime(2  value: string | number | Date,3  options?: Intl.DateTimeFormatOptions & {4    locale?: string5    scope?: IntlRuntime6  }7): string

Invalid date input returns ''.

Important options

Option	Type	Default	Effect
`locale`	`string`	runtime/DOM locale	One-off locale override
`scope`	`IntlRuntime`	`getIntl()`	Scope override (when using nested runtimes)
`dateStyle`	`full \| long \| medium \| short`	`undefined`	Preset date formatting
`timeStyle`	`full \| long \| medium \| short`	`undefined`	Preset time formatting
`calendar`	`string`	runtime default	Override calendar
`numberingSystem`	`string`	runtime default	Override digit system
`timeZone`	`string`	runtime default	IANA zone like `UTC`
`timeZoneName`	`long \| short`	`undefined`	Show timezone label
`hour12`	`boolean`	runtime default	Force 12h clock
`hourCycle`	`h11 \| h12 \| h23 \| h24`	runtime default	Alternative hour formatting
`weekday`	`narrow \| short \| long`	`undefined`	Day name output
`year`	`numeric \| 2-digit`	`undefined`	Year part
`month`	`numeric \| 2-digit \| narrow \| short \| long`	`undefined`	Month part
`day`	`numeric \| 2-digit`	`undefined`	Day part
`hour`	`numeric \| 2-digit`	`undefined`	Hour part
`minute`	`numeric \| 2-digit`	`undefined`	Minute part
`second`	`numeric \| 2-digit`	`undefined`	Second part
`fractionalSecondDigits`	`1 \| 2 \| 3`	`undefined`	Fractional seconds
`era`	`narrow \| short \| long`	`undefined`	Era label

Examples

Presets

1intlDateTime(Date.now(), { dateStyle: 'short' })2intlDateTime(Date.now(), { timeStyle: 'medium' })3intlDateTime(Date.now(), { dateStyle: 'long', timeStyle: 'short' })

Field-level formatting

1intlDateTime('2026-01-01T10:00:00Z', {2    weekday: 'long',3    year: 'numeric',4    month: 'long',5    day: '2-digit',6    hour: '2-digit',7    minute: '2-digit',8    timeZone: 'America/Sao_Paulo',9})

Locale and timezone variants

1intlDateTime('2026-01-01T10:00:00Z', {2    locale: 'en-US',3    timeZone: 'UTC',4    timeStyle: 'short',5})6 7intlDateTime('2026-01-01T10:00:00Z', {8    locale: 'fr-FR',9    timeZone: 'Europe/Paris',10    timeZoneName: 'short',11})

Scope integration

1import { createIntl, intlDateTime } from '@beforesemicolon/intl'2 3const scoped = createIntl({ locale: 'en-GB', messages: {} })4 5intlDateTime('2026-01-01T10:00:00Z', { scope: scoped })

Empty output rules

1intlDateTime('bad-date-string') // ''2intlDateTime(NaN as unknown as number) // ''