useDateFormatter

Date formatting and manipulation utilities built on @internationalized/date.

Usage

Use the auto-imported useDateFormatter composable for date formatting, conversion and manipulation, built on the @internationalized/date library for internationalized date handling.

<script setup lang="ts">
const formatter = useDateFormatter({ locale: 'en-US' })

const today = formatter.getToday()
const formattedDate = formatter.format(today)
// "Nov 29, 2025"

const isoString = formatter.toISO(today)
// "2025-11-29"
</script>

useDateFormatter provides locale-aware date formatting based on Intl.DateTimeFormat.
Supports bulk conversion of single dates, date ranges, date arrays and nested objects.
Specify a timezone via the timeZone option (defaults to the local timezone); identifiers follow the IANA timezone database specification.

All formatting and conversion methods have built-in error handling: passing null or undefined returns an empty string or null without throwing an exception.

Capabilities at a Glance

The table below covers the output shapes of useDateFormatter across common date scenarios:

当前 locale: zh-CN · timeZone: UTC

调用	返回值
format(today)	2026年6月29日
toISO(today)	2026-06-29
toTimestamp(today)	1782691200000
toUnixTimestamp(today)	1782691200
isWeekend(today)	false
isWeekday(today)	true
isToday(today)	true
getDayOfWeek(today)	0
getDayOfWeekName(today, "long")	星期一
getDayOfWeekName(today, "short")	周一
getStartOfMonth(today)	2026-06-01
getEndOfMonth(today)	2026-06-30
getStartOfYear(today)	2026-01-01
getEndOfYear(today)	2026-12-31
formatRange(start, end)	2026年6月29日 - 2026年7月6日
formatArray([d, d+1, d+2])	2026年6月29日, 2026年6月30日, 2026年7月1日
parse("2026-01-01")?.toString()	2026-01-01

<script setup lang="ts">
const f = useDateFormatter({ locale: 'zh-CN' })
const today = f.getToday()
const range = { start: today, end: today.add({ days: 7 }) }
const list = [today, today.add({ days: 1 }), today.add({ days: 2 })]

const rows = [
  { method: 'format(today)', value: f.format(today) },
  { method: 'toISO(today)', value: f.toISO(today) },
  { method: 'toTimestamp(today)', value: f.toTimestamp(today) },
  { method: 'toUnixTimestamp(today)', value: f.toUnixTimestamp(today) },
  { method: 'isWeekend(today)', value: f.isWeekend(today) },
  { method: 'isWeekday(today)', value: f.isWeekday(today) },
  { method: 'isToday(today)', value: f.isToday(today) },
  { method: 'getDayOfWeek(today)', value: f.getDayOfWeek(today) },
  { method: 'getDayOfWeekName(today, "long")', value: f.getDayOfWeekName(today, 'long') },
  { method: 'getDayOfWeekName(today, "short")', value: f.getDayOfWeekName(today, 'short') },
  { method: 'getStartOfMonth(today)', value: f.toISO(f.getStartOfMonth(today)) },
  { method: 'getEndOfMonth(today)', value: f.toISO(f.getEndOfMonth(today)) },
  { method: 'getStartOfYear(today)', value: f.toISO(f.getStartOfYear(today)) },
  { method: 'getEndOfYear(today)', value: f.toISO(f.getEndOfYear(today)) },
  { method: 'formatRange(start, end)', value: f.formatRange(range.start, range.end) },
  { method: 'formatArray([d, d+1, d+2])', value: f.formatArray(list) },
  { method: 'parse("2026-01-01")?.toString()', value: f.parse('2026-01-01')?.toString() ?? 'null' }
]

const columns = [
  { accessorKey: 'method', header: '调用' },
  { accessorKey: 'value', header: '返回值' }
]
</script>

<template>
  <div class="flex flex-col gap-3">
    <p class="text-xs text-muted">
      当前 locale: {{ f.locale }} · timeZone: {{ f.timeZone }}
    </p>
    <MDataTable :columns="columns" :data="rows" stripe bordered density="compact" />
  </div>
</template>

Integration with AutoForm

When using date fields in AutoForm, use convertToISO() for bulk conversion before submitting:

<script setup lang="ts">
const { afz } = useAutoForm()
const formatter = useDateFormatter()

const schema = afz.object({
  eventDate: afz.calendarDate(),
  eventRange: afz.calendarDate({
    controlProps: { mode: 'range' }
  })
})

const formData = ref()

async function handleSubmit() {
  // Automatically handle conversion for all date fields
  const payload = formatter.convertToISO(formData.value)

  // payload.eventDate: "2025-11-29"
  // payload.eventRange: { start: "2025-11-01", end: "2025-11-30" }

  await api.submit(payload)
}
</script>

convertToISO automatically traverses all nested date fields while preserving the object structure — no manual conversion required.

API

useDateFormatter()

useDateFormatter(options?: DateFormatterOptions): DateFormatter

Creates a date formatter instance.

Parameters

options

DateFormatterOptions

Date formatter configuration options.

Returns

Returns a date formatter object with the following methods and properties.

Formatting Methods

format()

(date: DateValue | undefined | null) => string

Format a single date as a localized string.

formatRange()

(start: DateValue | undefined | null, end: DateValue | undefined | null, separator?: string) => string

Format a date range. Default separator is ' - '.

formatArray()

(dates: DateValue[] | undefined | null, separator?: string) => string

Format an array of dates. Default separator is ', '.

Conversion Methods

toISO()

(date: DateValue | undefined | null) => string

Convert to an ISO 8601 string.

toDate()

(date: DateValue | undefined | null) => Date | null

Convert to a JavaScript Date object.

toTimestamp()

(date: DateValue | undefined | null) => number | null

Convert to a timestamp (milliseconds).

toUnixTimestamp()

(date: DateValue | undefined | null) => number | null

Convert to a Unix timestamp (seconds).

parse()

(value: string) => DateValue | null

Parse an ISO 8601 date string. Automatically identifies CalendarDate, CalendarDateTime or ZonedDateTime.

Utility Methods — Getting Dates

getToday()

() => CalendarDate

Get today's date.

getNow()

() => ZonedDateTime

Get the current date and time.

getStartOfWeek()