1---
2category: Time
3---
4 
5# useDateFormat
6 
7Get the formatted date according to the string of tokens passed in, inspired
8by [dayjs](https://github.com/iamkun/dayjs).
9 
10**List of all available formats (HH:mm:ss by default):**
11 
12| Format | Output                   | Description                             |
13| ------ | ------------------------ | --------------------------------------- |
14| `Yo`   | 2018th                   | Ordinal formatted year                  |
15| `YY`   | 18                       | Two-digit year                          |
16| `YYYY` | 2018                     | Four-digit year                         |
17| `M`    | 1-12                     | The month, beginning at 1               |
18| `Mo`   | 1st, 2nd, ..., 12th      | The month, ordinal formatted            |
19| `MM`   | 01-12                    | The month, 2-digits                     |
20| `MMM`  | Jan-Dec                  | The abbreviated month name              |
21| `MMMM` | January-December         | The full month name                     |
22| `D`    | 1-31                     | The day of the month                    |
23| `Do`   | 1st, 2nd, ..., 31st      | The day of the month, ordinal formatted |
24| `DD`   | 01-31                    | The day of the month, 2-digits          |
25| `H`    | 0-23                     | The hour                                |
26| `Ho`   | 0th, 1st, 2nd, ..., 23rd | The hour, ordinal formatted             |
27| `HH`   | 00-23                    | The hour, 2-digits                      |
28| `h`    | 1-12                     | The hour, 12-hour clock                 |
29| `ho`   | 1st, 2nd, ..., 12th      | The hour, 12-hour clock, sorted         |
30| `hh`   | 01-12                    | The hour, 12-hour clock, 2-digits       |
31| `m`    | 0-59                     | The minute                              |
32| `mo`   | 0th, 1st, ..., 59th      | The minute, ordinal formatted           |
33| `mm`   | 00-59                    | The minute, 2-digits                    |
34| `s`    | 0-59                     | The second                              |
35| `so`   | 0th, 1st, ..., 59th      | The second, ordinal formatted           |
36| `ss`   | 00-59                    | The second, 2-digits                    |
37| `SSS`  | 000-999                  | The millisecond, 3-digits               |
38| `A`    | AM PM                    | The meridiem                            |
39| `AA`   | A.M. P.M.                | The meridiem, periods                   |
40| `a`    | am pm                    | The meridiem, lowercase                 |
41| `aa`   | a.m. p.m.                | The meridiem, lowercase and periods     |
42| `d`    | 0-6                      | The day of the week, with Sunday as 0   |
43| `dd`   | S-S                      | The min name of the day of the week     |
44| `ddd`  | Sun-Sat                  | The short name of the day of the week   |
45| `dddd` | Sunday-Saturday          | The name of the day of the week         |
46| `z`    | GMT, GMT+1               | The timezone with offset                |
47| `zz`   | GMT, GMT+1               | The timezone with offset                |
48| `zzz`  | GMT, GMT+1               | The timezone with offset                |
49| `zzzz` | GMT, GMT+01:00           | The long timezone with offset           |
50 
51- Meridiem is customizable by defining `customMeridiem` in `options`.
52 
53## Usage
54 
55### Basic
56 
57```vue
58<script setup lang="ts">
59import { useDateFormat, useNow } from '@vueuse/core'
60 
61const formatted = useDateFormat(useNow(), 'YYYY-MM-DD HH:mm:ss')
62</script>
63 
64<template>
65  <div>{{ formatted }}</div>
66</template>
67```
68 
69### Use with locales
70 
71```vue
72<script setup lang="ts">
73import { useDateFormat, useNow } from '@vueuse/core'
74 
75const formatted = useDateFormat(useNow(), 'YYYY-MM-DD (ddd)', { locales: 'en-US' })
76</script>
77 
78<template>
79  <div>{{ formatted }}</div>
80</template>
81```
82 
83### Use with custom meridiem
84 
85```vue
86<script setup lang="ts">
87import { useDateFormat } from '@vueuse/core'
88 
89function customMeridiem(hours: number, minutes: number, isLowercase?: boolean, hasPeriod?: boolean) {
90  const m = hours > 11 ? (isLowercase ? 'μμ' : 'ΜΜ') : (isLowercase ? 'πμ' : 'ΠΜ')
91  return hasPeriod ? m.split('').reduce((acc, current) => acc += `${current}.`, '') : m
92}
93 
94const am = useDateFormat('2022-01-01 05:05:05', 'hh:mm:ss A', { customMeridiem })
95// am.value = '05:05:05 ΠΜ'
96const pm = useDateFormat('2022-01-01 17:05:05', 'hh:mm:ss AA', { customMeridiem })
97// pm.value = '05:05:05 Μ.Μ.'
98</script>
99```
100 
101## Type Declarations
102 
103```ts
104export type DateLike = Date | number | string | undefined
105export interface UseDateFormatOptions {
106  /**
107   * The locale(s) to used for dd/ddd/dddd/MMM/MMMM format
108   *
109   * [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#locales_argument).
110   */
111  locales?: MaybeRefOrGetter<Intl.LocalesArgument>
112  /**
113   * A custom function to re-modify the way to display meridiem
114   *
115   */
116  customMeridiem?: (
117    hours: number,
118    minutes: number,
119    isLowercase?: boolean,
120    hasPeriod?: boolean,
121  ) => string
122}
123export declare function formatDate(
124  date: Date,
125  formatStr: string,
126  options?: UseDateFormatOptions,
127): string
128export declare function normalizeDate(date: DateLike): Date
129export type UseDateFormatReturn = ComputedRef<string>
130/**
131 * Get the formatted date according to the string of tokens passed in.
132 *
133 * @see https://vueuse.org/useDateFormat
134 * @param date - The date to format, can either be a `Date` object, a timestamp, or a string
135 * @param formatStr - The combination of tokens to format the date
136 * @param options - UseDateFormatOptions
137 *
138 * @__NO_SIDE_EFFECTS__
139 */
140export declare function useDateFormat(
141  date: MaybeRefOrGetter<DateLike>,
142  formatStr?: MaybeRefOrGetter<string>,
143  options?: UseDateFormatOptions,
144): UseDateFormatReturn
145```
146