+ = ngx-date-fns

date-fns pipes for Angular applications.

Requirememnts

The latest version of this library requires:

date-fns >= v3.0.0.
Angular >= v17.0.0.

Installation

npm install --save date-fns
npm install --save ngx-date-fns

Installation for date-fns v2

npm install --save date-fns@2.30.0
npm install --save ngx-date-fns@10.0.1
ngx-date-fns@10.0.1 docs

⚠️ There's a range of date-fns versions for which tree shaking is broken, so we recommend that you either install v2.16.1 or >= v2.21.1.

Installation for date-fns v1

npm install --save date-fns@1.29.0
npm install --save ngx-date-fns@4.0.3
ngx-date-fns@4.0.3 docs

Basic Usage

stackblitz example

import { CommonModule } from '@angular/common';
import { Component } from '@angular/core';
import { bootstrapApplication } from '@angular/platform-browser';
import 'zone.js';
import { es } from 'date-fns/locale';
import { DateFnsModule } from 'ngx-date-fns';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [CommonModule, DateFnsModule],
  template: `
    <p>{{ dateOne | dfnsFormat: 'MM/dd/yyyy' }}</p>
    <p>{{ [dateOne, dateTwo] | dfnsMin | dfnsFormat: 'EEE LLLL d yyyy' }}</p>
    <p>
      {{ [dateOne, dateTwo] | dfnsMax | dfnsFormat: 'EEE LLLL d yyyy' }}
    </p>
    <p>
      {{ dateThree | dfnsFormatDistanceToNow: options }} - (Explicit 'es'
      locale)
    </p>
    <p>{{ 0 | dfnsWeekdayName: 'full':options }} - (Explicit 'es' locale)</p>
    <p>
      {{
        '12 de Marzo'
          | dfnsParse: parseFormat:parseDate:parseLocale
          | dfnsFormat: 'MM/dd/yyyy'
      }}
    </p>
  `
})
export class App {
  dateOne = new Date(2016, 0, 1);
  dateTwo = new Date(2017, 0, 1);
  dateThree: Date;
  options = {
    locale: es,
    addSuffix: true
  };
  parseDate = new Date(2010, 0, 1);
  parseFormat = `do 'de' MMMM`;
  parseLocale = { locale: es };

  constructor() {
    this.dateThree = new Date();
    this.dateThree.setDate(this.dateThree.getDate() - 6);
  }
}

bootstrapApplication(App);

The output:

01/01/2016
Fri January 1 2016
Sun January 1 2017
hace 6 días - (Explicit 'es' locale)
lunes - (Explicit 'es' locale)
03/12/2010

Working with locales

All locale-aware pipes use English by default.

Changing locale globally

Instead of passing the locale to each pipe via options you can set it globally in one single step by overriding the default DateFnsConfiguration implementation:

stackblitz example

// app.config.ts
import { ApplicationConfig } from '@angular/core';
import { DateFnsConfigurationService } from 'ngx-date-fns';
import { fr } from 'date-fns/locale';

const frenchConfig = new DateFnsConfigurationService();
frenchConfig.setLocale(fr);

export const appConfig: ApplicationConfig = {
  providers: [{ provide: DateFnsConfigurationService, useValue: frenchConfig }]
};

// main.ts
import { CommonModule } from '@angular/common';
import { Component } from '@angular/core';
import { bootstrapApplication } from '@angular/platform-browser';
import 'zone.js';
import { es } from 'date-fns/locale';
import { DateFnsModule } from 'ngx-date-fns';
import { appConfig } from './app.config';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [CommonModule, DateFnsModule],
  template: `
    (...)
  `
})
export class App {
  // (...)
}

bootstrapApplication(App, appConfig).catch(err => console.error(err));

Changing locale at runtime

It is also possible to change the default locale at runtime:

stackblitz example

import { CommonModule } from '@angular/common';
import { Component } from '@angular/core';
import { bootstrapApplication } from '@angular/platform-browser';
import 'zone.js';
import { es, de } from 'date-fns/locale';
import { DateFnsConfigurationService, DateFnsModule } from 'ngx-date-fns';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [CommonModule, DateFnsModule],
  template: `
    <p>{{ dateOne | dfnsFormat: 'EEE LLLL d yyyy' }}</p>
    <hr />
    Set default locale to: <a href="#" (click)="changeToGerman()">German</a>,
    <a href="#" (click)="changeToSpanish()">Spanish</a>.
  `
})
export class App {
  dateOne = new Date(2016, 0, 1);
  constructor(public config: DateFnsConfigurationService) {}
  changeToGerman() {
    this.config.setLocale(de);
  }
  changeToSpanish() {
    this.config.setLocale(es);
  }
}

bootstrapApplication(App);

Pure or impure?

Should I use the pure or impure version of the locale-aware pipes?

The answer is quite simple:

Do you set the locale only once when the application starts?
- Use only pure pipes.
Do you need to change the locale at runtime?
- Use impure pipes.

The main difference is that pure pipes do not get notified when the locale is changed via DateFnsConfiguration.setLocale(locale: Locale), because the instance is not kept in memory. Impure pipes, on the other hand, are kept in memory and listen for Locale change notifications, which adds some memory and performance overhead.

Available pipes

All pipes are pure unless stated otherwise.

Misc

Format

Since v7.0.0 invalid Dates will return an empty string instead of throwing an exception.

Get

Difference

Add

Subtract

End

Start

Last Day Of

Is...?

Utils

A collection of utilities built around date-fns functions.

dfnsFormatRelativeToNow

This pipe is (impure), but there's the pure version dfnsFormatRelativeToNowPure too.

Same as dfnsFormatRelative but the date to comapre against is always Date.now().

dfnsWeekdayName

This pipe is (impure)

Given a weekday number, returns its name.

@param `WeekdayNameFormat`

Optional weekday format. Allowed values are:

x1: One char. 'M' for Monday.
x2: Two chars. 'Mo' for Monday.
x3: Three chars. 'Mon' for Monday.
full: Full weekday name. 'Monday' for Monday.

Defaults to full.

@param `Locale`

Optional date-fns Locale object.

Optional locale object.

Basic example

<div>
  <!-- Prints Monday -->
  {{ 0 | dfnsWeekdayName }}
</div>
<div>
  <!-- Prints Mon -->
  {{ 0 | dfnsWeekdayName : 'x3' }}
</div>

Name		Name	Last commit message	Last commit date
Latest commit History 230 Commits
.github		.github
.vscode		.vscode
cypress		cypress
projects		projects
.editorconfig		.editorconfig
.gitignore		.gitignore
.prettierrc.json		.prettierrc.json
.travis.yml		.travis.yml
README.md		README.md
angular.json		angular.json
cypress.config.ts		cypress.config.ts
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

joanllenas/ngx-date-fns

Folders and files

Latest commit

History

Repository files navigation

+ = ngx-date-fns

Table Of Contents

Requirememnts

Installation

Installation for date-fns v2

Installation for date-fns v1

Basic Usage

Working with locales

Changing locale globally

Changing locale at runtime

Pure or impure?

Available pipes

Misc

Format

Get

Difference

Add

Subtract

End

Start

Last Day Of

Is...?

Utils

dfnsFormatRelativeToNow

dfnsWeekdayName

@param WeekdayNameFormat

@param Locale

Basic example

About

Topics

Resources

Stars

Watchers

Forks

Languages

@param `WeekdayNameFormat`

@param `Locale`