Skip to content

useDateFormat

Category
Export Size
807 B
Last Changed
last month

Get the formatted date according to the string of tokens passed in, inspired by dayjs.

List of all available formats (HH:mm:ss by default):

FormatOutputDescription
Yo2018thOrdinal formatted year
YY18Two-digit year
YYYY2018Four-digit year
M1-12The month, beginning at 1
Mo1st, 2nd, ..., 12thThe month, ordinal formatted
MM01-12The month, 2-digits
MMMJan-DecThe abbreviated month name
MMMMJanuary-DecemberThe full month name
D1-31The day of the month
Do1st, 2nd, ..., 31stThe day of the month, ordinal formatted
DD01-31The day of the month, 2-digits
H0-23The hour
Ho0th, 1st, 2nd, ..., 23rdThe hour, ordinal formatted
HH00-23The hour, 2-digits
h1-12The hour, 12-hour clock
ho1st, 2nd, ..., 12thThe hour, 12-hour clock, sorted
hh01-12The hour, 12-hour clock, 2-digits
m0-59The minute
mo0th, 1st, ..., 59thThe minute, ordinal formatted
mm00-59The minute, 2-digits
s0-59The second
so0th, 1st, ..., 59thThe second, ordinal formatted
ss00-59The second, 2-digits
SSS000-999The millisecond, 3-digits
AAM PMThe meridiem
AAA.M. P.M.The meridiem, periods
aam pmThe meridiem, lowercase
aaa.m. p.m.The meridiem, lowercase and periods
d0-6The day of the week, with Sunday as 0
ddS-SThe min name of the day of the week
dddSun-SatThe short name of the day of the week
ddddSunday-SaturdayThe name of the day of the week
  • Meridiem is customizable by defining customMeridiem in options.

Demo

2023-12-08 14:04:01

Formatter Editor :

Usage

Basic

vue
<script setup lang="ts">
import { useDateFormat, useNow } from '@vueuse/core'

const formatted = useDateFormat(useNow(), 'YYYY-MM-DD HH:mm:ss')
</script>

<template>
  <div>{{ formatted }}</div>
</template>

Use with locales

vue
<script setup lang="ts">
import { useDateFormat, useNow } from '@vueuse/core'

const formatted = useDateFormat(useNow(), 'YYYY-MM-DD (ddd)', { locales: 'en-US' })
</script>

<template>
  <div>{{ formatted }}</div>
</template>

Use with custom meridiem

vue
<script setup lang="ts">
import { useDateFormat } from '@vueuse/core'

function customMeridiem(hours: number, minutes: number, isLowercase?: boolean, hasPeriod?: boolean) {
  const m = hours > 11 ? (isLowercase ? 'μμ' : 'ΜΜ') : (isLowercase ? 'πμ' : 'ΠΜ')
  return hasPeriod ? m.split('').reduce((acc, current) => acc += `${current}.`, '') : m
}

const am = useDateFormat('2022-01-01 05:05:05', 'hh:mm:ss A', { customMeridiem })
// am.value = '05:05:05 ΠΜ'
const pm = useDateFormat('2022-01-01 17:05:05', 'hh:mm:ss AA', { customMeridiem })
// pm.value = '05:05:05 Μ.Μ.'
</script>

Type Declarations

Show Type Declarations
typescript
export type DateLike = Date | number | string | undefined
export interface UseDateFormatOptions {
  /**
   * The locale(s) to used for dd/ddd/dddd/MMM/MMMM format
   *
   * [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#locales_argument).
   */
  locales?: Intl.LocalesArgument
  /**
   * A custom function to re-modify the way to display meridiem
   *
   */
  customMeridiem?: (
    hours: number,
    minutes: number,
    isLowercase?: boolean,
    hasPeriod?: boolean,
  ) => string
}
export declare function formatDate(
  date: Date,
  formatStr: string,
  options?: UseDateFormatOptions,
): string
export declare function normalizeDate(date: DateLike): Date
/**
 * Get the formatted date according to the string of tokens passed in.
 *
 * @see https://vueuse.org/useDateFormat
 * @param date - The date to format, can either be a `Date` object, a timestamp, or a string
 * @param formatStr - The combination of tokens to format the date
 * @param options - UseDateFormatOptions
 */
export declare function useDateFormat(
  date: MaybeRefOrGetter<DateLike>,
  formatStr?: MaybeRefOrGetter<string>,
  options?: UseDateFormatOptions,
): ComputedRef<string>
export type UseDateFormatReturn = ReturnType<typeof useDateFormat>

Source

SourceDemoDocs

Contributors

Anthony Fu
webfansplz
Poet
Dachen
Dino Čamdžić
丶远方
sun0day
Levi (Nguyễn Lương Huy)
Vasya Ponomarenko
aki77
Black

Changelog

v10.6.0 on 11/9/2023
61ceb - feat: add date ordinal formatting (#3474)
v10.3.0 on 7/30/2023
d6428 - fix: handle zero properly (#3272)
v10.1.0 on 4/22/2023
a2147 - fix: Error if Y or YYY provided (#3001)
v10.0.0-beta.4 on 4/13/2023
4d757 - feat(types)!: rename MaybeComputedRef to MaybeRefOrGetter
0a72b - feat(toValue): rename resolveUnref to toValue
v9.3.0 on 9/26/2022
3fda6 - feat: support meridiem format (#2011)
39b27 - feat: support MMM and MMMM formatter (#2234)
v9.1.1 on 8/23/2022
0fdbb - fix(shared): resolve internal circular reference
v9.0.1 on 7/29/2022
5b1e0 - feat: support dd, ddd and dddd formatter (#1986)
v8.9.1 on 7/8/2022
a9ccc - feat(all): use MaybeComputedRef (#1768)

Released under the MIT License.