use-date-format

Format a date with a token pattern or Intl.DateTimeFormat options.

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 { formatDate, useDateFormat } from "@vizejs/composable/use-date-format";

Try it

Show a start time in a time zone

Format a timestamp with a token pattern and a reader-selected time zone.

Open the interactive example

What to observe: The talk starts 2026-10-24 01:00 in UTC and 2026-10-24 10:00 in Tokyo. Switch the format to see Sat 24 Oct, 1:00 AM.

Tokens follow common date libraries (YYYY, MM, DD, HH, mm, ddd, A); wrap literal text in brackets. Both the pattern and timeZone can be refs.

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 { ref } from "vue";
import { useDateFormat } from "@vizejs/composable/use-date-format";

const start = Date.UTC(2026, 9, 24, 1, 0);
const timeZone = ref("UTC");
const pattern = ref("YYYY-MM-DD HH:mm");
const formatted = useDateFormat(start, pattern, { timeZone });
</script>

<template>
  <div class="composable-example">
    <p>Show a talk's start time with a format string, in the time zone the reader chooses.</p>
    <label>
      Time zone
      <select v-model="timeZone">
        <option value="UTC">UTC</option>
        <option value="Asia/Tokyo">Tokyo</option>
        <option value="America/New_York">New York</option>
      </select>
    </label>
    <label>
      Format
      <select v-model="pattern">
        <option value="YYYY-MM-DD HH:mm">YYYY-MM-DD HH:mm</option>
        <option value="ddd D MMM, h:mm A">ddd D MMM, h:mm A</option>
      </select>
    </label>
    <output aria-live="polite">Starts {{ formatted }}</output>
  </div>
</template>

Runtime contract

API

formatDate

Format a date with a token pattern or Intl.DateTimeFormat options. Pure and deterministic: locale and time zone default to fixed values ("en", "UTC") rather than host settings, so the same input renders identically on server and client. Calendar fields are computed in the requested time zone through Intl, so no host-zone arithmetic leaks in.

function formatDate( input: DateFormatInput, format: string | Intl.DateTimeFormatOptions = "HH:mm:ss", options: FormatDateOptions = {}, ): string

formatDate(0, "YYYY-MM-DD HH:mm:ss"); // "1970-01-01 00:00:00"
formatDate(0, "dddd, MMMM D [at] h:mm A", { locale: "en", timeZone: "Asia/Tokyo" });
formatDate(0, { dateStyle: "long" }, { locale: "ja" }); // "1970年1月1日"

useDateFormat

Reactive formatted date. Wraps formatDate in a computed ref; the date, the format, the locale, and the time zone are all reactive. Deterministic defaults ("en", "UTC") keep server and client output identical. No timers, no globals, nothing to dispose.

function useDateFormat( input: MaybeRefOrGetter<DateFormatInput>, format: MaybeRefOrGetter<string | Intl.DateTimeFormatOptions> = "HH:mm:ss", options: UseDateFormatOptions = {}, ): ComputedRef<string>

const label = useDateFormat(() => event.value.startsAt, "ddd, MMM D HH:mm", {
  locale: () => locale.value,
  timeZone: "Europe/Paris",
});

Types

FormatDateOptions

Options for formatDate.

UseDateFormatOptions

Options for useDateFormat.