use-date-time-format

Format dates and times reactively with Intl.DateTimeFormat.

Minimal setup

Use a Vue 3.5+ project with Vue SFC compilation configured (see Vite+ integration).

vp install @vizejs/composable

Import the entry directly. Call lifecycle-bound utilities inside <script setup> so cleanup follows the component scope; consult the runtime contract for this entry's SSR and hydration behavior.

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

Try it

Write a date for each reader

Format a date with Intl.DateTimeFormat so its order, month names and separators match the locale.

Open the interactive example

What to observe: October 24, 2026 becomes 24. Oktober 2026 in German and 2026年10月24日 in Japanese.

Pass timeZone when the date must not shift with the reader's clock. formatRange and formatToParts are also returned.

Compare the initial and interacted states

Copy the example

Save this complete SFC in your Vue project. Its public imports and source are the same ones executed in the preview.

<script setup lang="ts">
import { computed, ref } from "vue";
import { useDateTimeFormat } from "@vizejs/composable/use-date-time-format";

const locale = ref("en-US");
const date = new Date(Date.UTC(2026, 9, 24));
const { formatted } = useDateTimeFormat(
  date,
  computed(() => ({ locale: locale.value, dateStyle: "long" as const, timeZone: "UTC" })),
);
</script>

<template>
  <div class="composable-example">
    <p>Write a conference date the way each reader writes dates.</p>
    <label>
      Reader locale
      <select v-model="locale">
        <option value="en-US">English (United States)</option>
        <option value="de-DE">German (Germany)</option>
        <option value="ja-JP">Japanese (Japan)</option>
      </select>
    </label>
    <output aria-live="polite">{{ formatted }}</output>
  </div>
</template>

Runtime contract

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.

DateTimeFormatControls

Reactive date formatting returned by useDateTimeFormat.