use-date-time-format

Format dates and times reactively with Intl.DateTimeFormat.


Package	`@vizejs/composable/use-date-time-format`
Own the source	`vize lib pull composable:use-date-time-format`
Runtime exports	`useDateTimeFormat`
Gzip budget	2304 B

Usage

import { useDateTimeFormat } from "@vizejs/composable/use-date-time-format";

Runtime contract

Utility	Category	Stability	SSR	Hydration	Cleanup	Targets	Host globals	Uses
`useDateTimeFormat`	i18n	experimental	deterministic-fallback	caller-managed	none	web, server, worker, native, desktop, terminal	`Intl`, `window`	`useLocale`

API

`useDateTimeFormat`

Format dates and times reactively with Intl.DateTimeFormat. The formatter follows the reactive options (including locale) and is cached per locale and option set through useLocale. For hydration-stable output pass both locale and timeZone: otherwise the server uses "en" and its own zone. Invalid options surface as the platform's RangeError on first read; invalid dates render as "". No listeners or timers are created — combine with a clock composable for live-updating output.

function useDateTimeFormat( value?: MaybeRefOrGetter<FormattableDate | null | undefined>, options: MaybeRefOrGetter<UseDateTimeFormatOptions> = {}, ): DateTimeFormatControls

const { formatted } = useDateTimeFormat(date, { locale: "en-GB", dateStyle: "long", timeZone: "UTC" });

Types

`UseDateTimeFormatOptions`

Options for useDateTimeFormat.

Member	Type	Description
`locale`?	`string \| Intl.Locale`	Locale used for formatting. Pass it explicitly (and a `timeZone`) for server rendering: the server falls back to `"en"` and its own time zone.

`DateTimeFormatControls`

Reactive date formatting returned by useDateTimeFormat.

Member	Type	Description
`locale`	`ComputedRef<string>`	Canonical locale in use.
`formatter`	`ComputedRef<Intl.DateTimeFormat>`	Cached formatter for the current locale and options.
`formatted`	`ComputedRef<string>`	Formatted `value`, or `""` while the value is `null`/`undefined` or an invalid date.
`format`	`(value: FormattableDate) => string`	Format any date with the current formatter.
`formatToParts`	`(value: FormattableDate) => Intl.DateTimeFormatPart[]`	Format any date into locale-aware parts.
`formatRange`	`(start: FormattableDate, end: FormattableDate) => string`	Format a date range, collapsing shared fields (for example `"Jan 3 – 5, 2026"`).