Skip to content
On this page

useTimeAgo

Category
Export Size
1.93 kB
Last Changed
2 hours ago

Reactive time ago. Automatically update the time ago string when the time changes.

Demo

just now
0ms

Usage

js
import { useTimeAgo } from '@vueuse/core'

const timeAgo = useTimeAgo(new Date(2021, 0, 1))
import { useTimeAgo } from '@vueuse/core'

const timeAgo = useTimeAgo(new Date(2021, 0, 1))

Component Usage

This function also provides a renderless component version via the @vueuse/components package. Learn more about the usage.

html
<UseTimeAgo v-slot="{ timeAgo }" :time="new Date(2021, 0, 1)">
  Time Ago: {{ timeAgo }}
</UseTimeAgo>
<UseTimeAgo v-slot="{ timeAgo }" :time="new Date(2021, 0, 1)">
  Time Ago: {{ timeAgo }}
</UseTimeAgo>

Non-Reactivity Usage

In case you don't need the reactivity, you can use the formatTimeAgo function to get the formatted string instead of a Ref.

js
import { formatTimeAgo } from '@vueuse/core'

const timeAgo = formatTimeAgo(new Date(2021, 0, 1)) // string
import { formatTimeAgo } from '@vueuse/core'

const timeAgo = formatTimeAgo(new Date(2021, 0, 1)) // string

Type Declarations

Show Type Declarations
typescript
export declare type UseTimeAgoFormatter<T = number> = (
  value: T,
  isPast: boolean
) => string
export declare type UseTimeAgoUnitNamesDefault =
  | "second"
  | "minute"
  | "hour"
  | "day"
  | "week"
  | "month"
  | "year"
export interface UseTimeAgoMessagesBuiltIn {
  justNow: string
  past: string | UseTimeAgoFormatter<string>
  future: string | UseTimeAgoFormatter<string>
  invalid: string
}
export declare type UseTimeAgoMessages<
  UnitNames extends string = UseTimeAgoUnitNamesDefault
> = UseTimeAgoMessagesBuiltIn &
  Record<UnitNames, string | UseTimeAgoFormatter<number>>
export interface FormatTimeAgoOptions<
  UnitNames extends string = UseTimeAgoUnitNamesDefault
> {
  /**
   * Maximum unit (of diff in milliseconds) to display the full date instead of relative
   *
   * @default undefined
   */
  max?: UnitNames | number
  /**
   * Formatter for full date
   */
  fullDateFormatter?: (date: Date) => string
  /**
   * Messages for formatting the string
   */
  messages?: UseTimeAgoMessages<UnitNames>
  /**
   * Minimum display time unit (default is minute)
   *
   * @default false
   */
  showSecond?: boolean
  /**
   * Rounding method to apply.
   *
   * @default 'round'
   */
  rounding?: "round" | "ceil" | "floor" | number
  /**
   * Custom units
   */
  units?: UseTimeAgoUnit<UseTimeAgoUnitNamesDefault>[]
}
export interface UseTimeAgoOptions<
  Controls extends boolean,
  UnitNames extends string = UseTimeAgoUnitNamesDefault
> extends FormatTimeAgoOptions<UnitNames> {
  /**
   * Expose more controls
   *
   * @default false
   */
  controls?: Controls
  /**
   * Intervals to update, set 0 to disable auto update
   *
   * @default 30_000
   */
  updateInterval?: number
}
export interface UseTimeAgoUnit<
  Unit extends string = UseTimeAgoUnitNamesDefault
> {
  max: number
  value: number
  name: Unit
}
export declare type UseTimeAgoReturn<Controls extends boolean = false> =
  Controls extends true
    ? {
        timeAgo: ComputedRef<string>
      } & Pausable
    : ComputedRef<string>
/**
 * Reactive time ago formatter.
 *
 * @see https://vueuse.org/useTimeAgo
 * @param options
 */
export declare function useTimeAgo<
  UnitNames extends string = UseTimeAgoUnitNamesDefault
>(
  time: MaybeComputedRef<Date | number | string>,
  options?: UseTimeAgoOptions<false, UnitNames>
): UseTimeAgoReturn<false>
export declare function useTimeAgo<
  UnitNames extends string = UseTimeAgoUnitNamesDefault
>(
  time: MaybeComputedRef<Date | number | string>,
  options: UseTimeAgoOptions<true, UnitNames>
): UseTimeAgoReturn<true>
export declare function foramtTimeAgo<
  UnitNames extends string = UseTimeAgoUnitNamesDefault
>(
  from: Date,
  options?: FormatTimeAgoOptions<UnitNames>,
  now?: Date | number
): string
export declare type UseTimeAgoFormatter<T = number> = (
  value: T,
  isPast: boolean
) => string
export declare type UseTimeAgoUnitNamesDefault =
  | "second"
  | "minute"
  | "hour"
  | "day"
  | "week"
  | "month"
  | "year"
export interface UseTimeAgoMessagesBuiltIn {
  justNow: string
  past: string | UseTimeAgoFormatter<string>
  future: string | UseTimeAgoFormatter<string>
  invalid: string
}
export declare type UseTimeAgoMessages<
  UnitNames extends string = UseTimeAgoUnitNamesDefault
> = UseTimeAgoMessagesBuiltIn &
  Record<UnitNames, string | UseTimeAgoFormatter<number>>
export interface FormatTimeAgoOptions<
  UnitNames extends string = UseTimeAgoUnitNamesDefault
> {
  /**
   * Maximum unit (of diff in milliseconds) to display the full date instead of relative
   *
   * @default undefined
   */
  max?: UnitNames | number
  /**
   * Formatter for full date
   */
  fullDateFormatter?: (date: Date) => string
  /**
   * Messages for formatting the string
   */
  messages?: UseTimeAgoMessages<UnitNames>
  /**
   * Minimum display time unit (default is minute)
   *
   * @default false
   */
  showSecond?: boolean
  /**
   * Rounding method to apply.
   *
   * @default 'round'
   */
  rounding?: "round" | "ceil" | "floor" | number
  /**
   * Custom units
   */
  units?: UseTimeAgoUnit<UseTimeAgoUnitNamesDefault>[]
}
export interface UseTimeAgoOptions<
  Controls extends boolean,
  UnitNames extends string = UseTimeAgoUnitNamesDefault
> extends FormatTimeAgoOptions<UnitNames> {
  /**
   * Expose more controls
   *
   * @default false
   */
  controls?: Controls
  /**
   * Intervals to update, set 0 to disable auto update
   *
   * @default 30_000
   */
  updateInterval?: number
}
export interface UseTimeAgoUnit<
  Unit extends string = UseTimeAgoUnitNamesDefault
> {
  max: number
  value: number
  name: Unit
}
export declare type UseTimeAgoReturn<Controls extends boolean = false> =
  Controls extends true
    ? {
        timeAgo: ComputedRef<string>
      } & Pausable
    : ComputedRef<string>
/**
 * Reactive time ago formatter.
 *
 * @see https://vueuse.org/useTimeAgo
 * @param options
 */
export declare function useTimeAgo<
  UnitNames extends string = UseTimeAgoUnitNamesDefault
>(
  time: MaybeComputedRef<Date | number | string>,
  options?: UseTimeAgoOptions<false, UnitNames>
): UseTimeAgoReturn<false>
export declare function useTimeAgo<
  UnitNames extends string = UseTimeAgoUnitNamesDefault
>(
  time: MaybeComputedRef<Date | number | string>,
  options: UseTimeAgoOptions<true, UnitNames>
): UseTimeAgoReturn<true>
export declare function foramtTimeAgo<
  UnitNames extends string = UseTimeAgoUnitNamesDefault
>(
  from: Date,
  options?: FormatTimeAgoOptions<UnitNames>,
  now?: Date | number
): string

Source

SourceDemoDocs

Contributors

Anthony Fu
Joaquín Sánchez
Connor 'Birb' McCormick
836334258
sun0day
azaleta
vaakian X
Jelf
wheat
Alex Kozack

Changelog

v9.8.0 on 12/20/2022
f40a0 - fix: rounding unit fallback
9293c - feat: non-reactive version formatTimeAgo
v9.7.0 on 12/16/2022
324de - feat: custom units, number rounding
a7dc6 - feat: add floor and ceil value calculation (#2543)
0c333 - fix: add showSecond prop to component (#2547)
v9.3.0 on 9/26/2022
553f0 - feat: new showSecond option (#2209)
v8.9.1 on 7/8/2022
a9ccc - feat(all): use MaybeComputedRef (#1768)

Released under the MIT License.