+ = ngx-date-fns

date-fns pipes for Angular 2.0 and above.

Table Of Contents

• Installation
• date-fns v1 support
• Basic Usage
• Working with locales
  • Changing locale globally
  • Changing locale at runtime
  • Pure or impure?
• Tree shaking date-fns
• Available pipes 📚
  • Misc. pipes
  • Format... pipes
  • Get... pipes
  • Difference... pipes
  • Add... pipes
  • Subtract... pipes
  • End... pipes
  • Start... pipes
  • Last day of... pipes
  • Is... pipes
• Utils

Installation

This library requires date-fns >= v2.16.0.

⚠️ We recommend pinning your date-fns version to 2.16.1 until this issue, which prevents tree shaking from working, is fixed.

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

date-fns v1 support

• npm install --save [email protected]
• npm install --save [email protected]
• [email protected] docs

Basic Usage

Import DateFnsModule into your app's module:

import { DateFnsModule } from 'ngx-date-fns';

@NgModule({
  imports: [
    // (...)
    DateFnsModule.forRoot()
  ]
})

In lazy loaded module declarations use imports: [DateFnsModule].

import { Component } from '@angular/core';
import { es } from 'date-fns/locale';

@Component({
  selector: 'my-component',
  template: `
    <p>{{ dateOne | dfnsFormat: 'yyyy/MM/dd' }}</p>
    <p>{{ [dateOne, dateTwo] | dfnsMin }}</p>
    <p>{{ [dateOne, dateTwo] | dfnsMax | dfnsFormat: 'EEE LLL d yyyy' }}</p>
    <p>{{ dateThree | dfnsFormatDistanceToNow: options }}</p>
  `
})
export class AppComponent {
  dateOne = new Date(2016, 0, 1);
  dateTwo = new Date(2017, 0, 1);
  dateThree: Date;
  options = {
    locale: es,
    addSuffix: true
  };
  constructor() {
    this.dateThree = new Date();
    this.dateThree.setDate(this.dateThree.getDate() - 6);
  }
}

The output:

2016/01/01

Fri Jan 01 2016 00:00:00 GMT+0100 (Central European Standard Time)

Sun January 1 2017

hace 6 días

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:

import { DateFnsModule } from 'ngx-date-fns';
import { fr } from "date-fns/locale";

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

@NgModule({
  imports: [
    // (...)
    DateFnsModule.forRoot()
  ],
  providers: [
    // (...)
    { provide: DateFnsConfigurationService, useValue: frenchConfig } // <-- All pipes in French by default
  ]
})

Changing locale at runtime

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

import { Component } from '@angular/core';
import { DateFnsConfigurationService } from '../lib/src/date-fns-configuration.service';
import { es, de } from 'date-fns/locale';

@Component({
  selector: 'app-root',
  template: `
    <p>{{ dateOne | dfnsFormat: 'MM/dd/yyyy' }}</p>
    <hr />
    Set default locale to: <a  (click)="changeToGerman()">German</a>,
    <a  (click)="changeToSpanish()">Spanish</a>.
  `
})
export class AppComponent {
  dateOne = new Date(2016, 0, 1);
  constructor(public config: DateFnsConfigurationService) {}
  changeToGerman() {
    this.config.setLocale(de);
  }
  changeToSpanish() {
    this.config.setLocale(es);
  }
}

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.

Tree shaking date-fns

⚠️ We recommend pinning your date-fns version to 2.16.1 until this issue, which prevents tree shaking from working, is fixed.

The library itself is optimized to be tree-shakable by just importing DateFnsModule.forRoot() or selectively import pipes by calling them from ngx-date-fns package itself, as those were exported following the SCAM structure, for example:

// app.module.ts
import { fr } from 'date-fns/locale';
import { DateFnsConfigurationService } from 'ngx-date-fns';
import {
  FormatPipeModule,
  MinPipeModule,
  MaxPipeModule,
  FormatDistanceToNowPipeModule,
  WeekdayNamePipeModule,
  ParsePipeModule
} from 'ngx-date-fns';

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

@NgModule({
  // ... other module stuff
  imports: [
    // Selectively import
    FormatPipeModule,
    MinPipeModule,
    MaxPipeModule,
    FormatDistanceToNowPipeModule,
    WeekdayNamePipeModule,
    ParsePipeModule
  ],
  providers: [{ provide: DateFnsConfigurationService, useValue: frenchConfig }]
})
export class AppModule {}

You can test this by downloading this repo and running:

npm run analyze:app

This command will load a file in your browser where you will see that date-fns takes 63Kb, which is significantly less than the 286Kb of the whole library without tree shaking applied. (this, of course, will be much less after gzipping).

Also take into account that locale files tend to increase the final bundle size of date-fns as well.

Available pipes

All pipes are pure unless stated otherwise.

Misc

• impure)
  • dfnsParsePure
• dfnsParseIso
• dfnsClosestTo
• dfnsMin
• dfnsMax

Format

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

• impure)
  • dfnsFormatPure
• impure)
  • dfnsFormatDistancePure
• impure)
  • dfnsFormatDistanceStrictPure
• impure)
  • dfnsFormatDistanceToNowPure
• impure)
  • dfnsFormatDurationPure

Get

• dfnsGetOverlappingDaysInIntervals
• dfnsGetTime
• dfnsGetMilliseconds
• dfnsGetSeconds
• dfnsGetMinutes
• dfnsGetHours
• dfnsGetDate
• dfnsGetDayOfYear
• dfnsGetDay
• dfnsGetISODay
• dfnsGetISOWeek
• dfnsGetDaysInMonth
• dfnsGetMonth
• dfnsGetQuarter
• dfnsGetDaysInYear
• dfnsGetYear
• dfnsGetISOWeeksInYear
• dfnsGetISOWeekYear
• dfnsGetUnixTime
• impure)
  • dfnsGetWeekPure
• impure)
  • dfnsGetWeekOfMonthPure
• impure)
  • dfnsGetWeeksInMonthPure
• dfnsGetDecade
• impure)
  • dfnsGetWeekYearPure

Difference

• dfnsDifferenceInMilliseconds
• dfnsDifferenceInSeconds
• dfnsDifferenceInMinutes
• dfnsDifferenceInHours
• dfnsDifferenceInCalendarDays
• dfnsDifferenceInBusinessDays
• dfnsDifferenceInDays
• dfnsDifferenceInCalendarWeeks
• dfnsDifferenceInWeeks
• dfnsDifferenceInCalendarISOWeeks
• dfnsDifferenceInCalendarMonths
• dfnsDifferenceInMonths
• dfnsDifferenceInCalendarQuarters
• dfnsDifferenceInQuarters
• dfnsDifferenceInCalendarYears
• dfnsDifferenceInYears
• dfnsDifferenceInCalendarISOWeekYears
• dfnsDifferenceInISOWeekYears

Add

• dfnsAddMilliseconds
• dfnsAddSeconds
• dfnsAddMinutes
• dfnsAddHours
• dfnsAddBusinessDays
• dfnsAddDays
• dfnsAddWeeks
• dfnsAddMonths
• dfnsAddQuarters
• dfnsAddYears
• dfnsAddISOWeekYears

Subtract

• dfnsSubMilliseconds
• dfnsSubSeconds
• dfnsSubMinutes
• dfnsSubHours
• dfnsSubDays
• dfnsSubWeeks
• dfnsSubMonths
• dfnsSubQuarters
• dfnsSubYears
• dfnsSubISOWeekYears

End

• dfnsEndOfSecond
• dfnsEndOfMinute
• dfnsEndOfHour
• dfnsEndOfDay
• dfnsEndOfToday
• dfnsEndOfTomorrow
• dfnsEndOfYesterday
• dfnsEndOfWeek
• dfnsEndOfISOWeek
• dfnsEndOfMonth
• dfnsEndOfQuarter
• dfnsEndOfYear
• dfnsEndOfISOWeekYear

Start

• dfnsStartOfSecond
• dfnsStartOfMinute
• dfnsStartOfHour
• dfnsStartOfDay
• dfnsStartOfToday
• dfnsStartOfTomorrow
• dfnsStartOfYesterday
• impure)
  • dfnsStartOfWeekPure
• dfnsStartOfISOWeek
• dfnsStartOfMonth
• dfnsStartOfQuarter
• dfnsStartOfYear
• dfnsStartOfISOWeekYear
• dfnsStartOfDecade
• impure)
  • dfnsStartOfWeekYearPure

Last Day Of

• impure)
  • dfnsLastDayOfWeekPure
• dfnsLastDayOfISOWeek
• dfnsLastDayOfMonth
• dfnsLastDayOfQuarter
• dfnsLastDayOfYear
• dfnsLastDayOfISOWeekYear
• dfnsLastDayOfDecade

Is...?

• dfnsIsAfter
• dfnsIsBefore
• dfnsIsDate
• dfnsIsEqual
• dfnsIsFuture
• dfnsIsPast
• dfnsIsValid
• dfnsIsToday
• dfnsIsWeekend
• dfnsIsSameMonth
• dfnsIsSameYear

Utils

A collection of utilities built around date-fns functions.

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>