useTimeAgo

Category

Time

Export Size

1.45 kB

Last Changed

5 days ago

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

Demo

Usage

import { useTimeAgo } from '@reause/core'

const timeAgo = useTimeAgo(new Date(2021, 0, 1)) // string, auto-updates over time

// also accepts timestamps and date strings
const fromNumber = useTimeAgo(1633036800000)
const fromString = useTimeAgo('2024-01-01T00:00:00.000Z')

// show the full date when the diff exceeds `max` (unit name or milliseconds)
const cutoff = useTimeAgo(new Date(2021, 0, 1), { max: 'day' })

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 controllable state.

import { formatTimeAgo } from '@reause/core'

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

Type Declarations

Toggle

export type UseTimeAgoFormatter<T = number> = (value: T, isPast: boolean) => string

export 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 type UseTimeAgoMessages<UnitNames extends string = UseTimeAgoUnitNamesDefault> = UseTimeAgoMessagesBuiltIn & Record<UnitNames, string | UseTimeAgoFormatter<number>>

export interface FormatTimeAgoOptions<UnitNames extends string = UseTimeAgoUnitNamesDefault> {
    max?: UnitNames | number;
    fullDateFormatter?: (date: Date) => string;
    messages?: UseTimeAgoMessages<UnitNames>;
    showSecond?: boolean;
    rounding?: 'round' | 'ceil' | 'floor' | number;
    units?: UseTimeAgoUnit<UnitNames>[];
}

export interface UseTimeAgoOptions<UnitNames extends string = UseTimeAgoUnitNamesDefault> extends FormatTimeAgoOptions<UnitNames> {
    updateInterval?: number;
}

export interface UseTimeAgoUnit<Unit extends string = UseTimeAgoUnitNamesDefault> {
    max: number;
    value: number;
    name: Unit;
}

export function formatTimeAgo<UnitNames extends string = UseTimeAgoUnitNamesDefault>(from: Date, options?: FormatTimeAgoOptions<UnitNames>, now?: Date | number): string

export function useTimeAgo<UnitNames extends string = UseTimeAgoUnitNamesDefault>(time: Date | number | string, options?: UseTimeAgoOptions<UnitNames>): string

Source

Source · Demo · VueUse

Contributors

Changelog

v0.1.0 on

96d35 - fix(core): resolve useTimeAgo audit findings (#669)

55039 - fix(core): resolve useNow audit findings (#610)