1---
2category: Time
3---
4 
5# useTimeAgo
6 
7Reactive time ago. Automatically update the time ago string when the time changes.
8 
9## Usage
10 
11```ts
12import { useTimeAgo } from '@vueuse/core'
13 
14const timeAgo = useTimeAgo(new Date(2021, 0, 1))
15```
16 
17## Component Usage
18 
19```vue
20<template>
21  <UseTimeAgo v-slot="{ timeAgo }" :time="new Date(2021, 0, 1)">
22    Time Ago: {{ timeAgo }}
23  </UseTimeAgo>
24</template>
25```
26 
27## Non-Reactivity Usage
28 
29In case you don't need the reactivity, you can use the `formatTimeAgo` function to get the formatted string instead of a Ref.
30 
31```ts
32import { formatTimeAgo } from '@vueuse/core'
33 
34const timeAgo = formatTimeAgo(new Date(2021, 0, 1)) // string
35```
36 
37## Type Declarations
38 
39```ts
40export type UseTimeAgoFormatter<T = number> = (
41  value: T,
42  isPast: boolean,
43) => string
44export type UseTimeAgoUnitNamesDefault =
45  | "second"
46  | "minute"
47  | "hour"
48  | "day"
49  | "week"
50  | "month"
51  | "year"
52export interface UseTimeAgoMessagesBuiltIn {
53  justNow: string
54  past: string | UseTimeAgoFormatter<string>
55  future: string | UseTimeAgoFormatter<string>
56  invalid: string
57}
58export type UseTimeAgoMessages<
59  UnitNames extends string = UseTimeAgoUnitNamesDefault,
60> = UseTimeAgoMessagesBuiltIn &
61  Record<UnitNames, string | UseTimeAgoFormatter<number>>
62export interface FormatTimeAgoOptions<
63  UnitNames extends string = UseTimeAgoUnitNamesDefault,
64> {
65  /**
66   * Maximum unit (of diff in milliseconds) to display the full date instead of relative
67   *
68   * @default undefined
69   */
70  max?: UnitNames | number
71  /**
72   * Formatter for full date
73   */
74  fullDateFormatter?: (date: Date) => string
75  /**
76   * Messages for formatting the string
77   */
78  messages?: UseTimeAgoMessages<UnitNames>
79  /**
80   * Minimum display time unit (default is minute)
81   *
82   * @default false
83   */
84  showSecond?: boolean
85  /**
86   * Rounding method to apply.
87   *
88   * @default 'round'
89   */
90  rounding?: "round" | "ceil" | "floor" | number
91  /**
92   * Custom units
93   */
94  units?: UseTimeAgoUnit<UnitNames>[]
95}
96export interface UseTimeAgoOptions<
97  Controls extends boolean,
98  UnitNames extends string = UseTimeAgoUnitNamesDefault,
99>
100  extends FormatTimeAgoOptions<UnitNames>, ConfigurableScheduler {
101  /**
102   * Expose more controls
103   *
104   * @default false
105   */
106  controls?: Controls
107  /**
108   * Intervals to update, set 0 to disable auto update
109   *
110   * @deprecated Please use `scheduler` option instead
111   * @default 30_000
112   */
113  updateInterval?: number
114}
115export interface UseTimeAgoUnit<
116  Unit extends string = UseTimeAgoUnitNamesDefault,
117> {
118  max: number
119  value: number
120  name: Unit
121}
122export type UseTimeAgoReturn<Controls extends boolean = false> =
123  Controls extends true
124    ? {
125        timeAgo: ComputedRef<string>
126      } & Pausable
127    : ComputedRef<string>
128/**
129 * Reactive time ago formatter.
130 *
131 * @see https://vueuse.org/useTimeAgo
132 *
133 * @__NO_SIDE_EFFECTS__
134 */
135export declare function useTimeAgo<
136  UnitNames extends string = UseTimeAgoUnitNamesDefault,
137>(
138  time: MaybeRefOrGetter<Date | number | string>,
139  options?: UseTimeAgoOptions<false, UnitNames>,
140): UseTimeAgoReturn<false>
141export declare function useTimeAgo<
142  UnitNames extends string = UseTimeAgoUnitNamesDefault,
143>(
144  time: MaybeRefOrGetter<Date | number | string>,
145  options: UseTimeAgoOptions<true, UnitNames>,
146): UseTimeAgoReturn<true>
147export declare function formatTimeAgo<
148  UnitNames extends string = UseTimeAgoUnitNamesDefault,
149>(
150  from: Date,
151  options?: FormatTimeAgoOptions<UnitNames>,
152  now?: Date | number,
153): string
154```
155