ngx-timeago

ngx-timeago

Live updating timestamps in Angular.

✨ Now with full standalone component support! Use with NgModules or standalone components.

https://ihym.github.io/ngx-timeago/

Get the complete changelog here: https://github.com/ihym/ngx-timeago/releases

• Installation
• Setup
• Usage
• Configuration
• Contribute

Installation

First you need to install the package:

pnpm add ngx-timeago

Choose the version corresponding to your Angular version:

Angular	ngx-timeago
20	4.x+
16,17,18,19	3.x+
10,11,12,13,14,15	2.x+
6,7,8,9	1.x+

Setup

ngx-timeago supports both standalone components and NgModule approaches.

Standalone Components (Recommended)

// main.ts
import { provideTimeago } from 'ngx-timeago';

bootstrapApplication(AppComponent, {
  providers: [provideTimeago()],
});

// component.ts
import { TimeagoPipe } from 'ngx-timeago';

@Component({
  standalone: true,
  imports: [TimeagoPipe],
  template: `{{ date | timeago }}`,
})
export class MyComponent {}

With custom configuration:

provideTimeago({
  formatter: { provide: TimeagoFormatter, useClass: CustomFormatter },
  clock: { provide: TimeagoClock, useClass: MyClock },
  intl: { provide: TimeagoIntl, useClass: CustomIntl },
});

NgModule Approach

import { TimeagoModule } from 'ngx-timeago';

@NgModule({
  imports: [TimeagoModule.forRoot()],
})
export class AppModule {}

With custom configuration:

TimeagoModule.forRoot({
  formatter: { provide: TimeagoFormatter, useClass: CustomFormatter },
  clock: { provide: TimeagoClock, useClass: MyClock },
  intl: { provide: TimeagoIntl, useClass: CustomIntl },
});

For lazy loaded modules, use forChild() instead of forRoot().

Usage

Using the Pipe

<div>{{ date | timeago }}</div>
<div>{{ date | timeago: live }}</div>

Using the Directive

<div timeago [date]="date"></div>
<div timeago [date]="date" [live]="live"></div>

The live parameter controls automatic updates (default: true).

Configuration

Internationalization (I18n)

By default, there is no intl service available, as the default formatter doesn't provide language support. You should provide one, if you end up with a formatter that needs it (either TimeagoCustomFormatter which is provided by the lib or your own). The purpose of the intl service is to contain all the necessary i18n strings used by your formatter.

export class MyIntl extends TimeagoIntl {
  // Customize strings
}

// Then provide it with TimeagoCustomFormatter
provideTimeago({
  intl: { provide: TimeagoIntl, useClass: MyIntl },
  formatter: { provide: TimeagoFormatter, useClass: TimeagoCustomFormatter },
});

There is support for a large number of languages out of the box. This support is based on the string objects taken from jquery-timeago.

To use any of the languages provided, you will have to import the language strings and feed them to the intl service.

import { Component } from '@angular/core';
import { TimeagoIntl } from 'ngx-timeago';
import { strings as englishStrings } from 'ngx-timeago/language-strings/en';

@Component({...})
export class MyComponent {
  constructor(private intl: TimeagoIntl) {
    this.intl.strings = englishStrings;
    this.intl.changes.next();
  }
}

See available languages.

Custom Formatter

Implement TimeagoFormatter to customize timestamp display:

import { TimeagoFormatter } from 'ngx-timeago';

export class CustomFormatter extends TimeagoFormatter {
  format(then: number): string {
    const seconds = Math.round(Math.abs(Date.now() - then) / 1000);
    if (seconds < 60) return 'just now';
    if (seconds < 3600) return Math.round(seconds / 60) + ' minutes ago';
    // ... your logic
  }
}

Then provide it: { provide: TimeagoFormatter, useClass: CustomFormatter }

See full example

Custom Clock

Implement TimeagoClock to control update intervals:

import { TimeagoClock } from 'ngx-timeago';
import { interval } from 'rxjs';

export class MyClock extends TimeagoClock {
  tick(then: number) {
    return interval(2000); // Update every 2 seconds
  }
}

Then provide it: { provide: TimeagoClock, useClass: MyClock }

See full example

Contribute

$ pnpm install
$ pnpm build:lib
$ pnpm start              # NgModule demo
$ pnpm start:standalone   # Standalone demo

Both demos available at http://localhost:4200

MIT © Vasilis Diakomanolis