+  = ngx-date-fns


date-fns pipes for Angular applications.

Table Of Contents

- Requirememnts
- Installation
- date-fns v4 support
- date-fns v3 support
- date-fns v2 support
- date-fns v1 support
- Issues / feature requests
- Basic Usage
- Working with locales
- Changing locale globally
- Changing locale at runtime
- _Pure_ or _impure_?
- 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

Requirememnts

The latest version of this library requires:

- date-fns = v4.x.x.
- Angular >= v17.0.0.

Installation

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

#### Installation for date-fns v3

- npm install --save date-fns@3.6.0
- npm install --save ngx-date-fns@11.0.1
- ngx-date-fns@11.0.1 docs

#### 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

Issues and Feature Requests

This library has been around for more than 8 years and is largely complete, so don’t expect frequent new releases. If you notice missing functionality or encounter a bug, though, don’t hesitate to visit https://github.com/joanllenas/ngx-date-fns/issues and open an issue!

Basic Usage

> stackblitz example

``typescript
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:

{{ dateOne | dfnsFormat: 'MM/dd/yyyy' }}

{{ [dateOne, dateTwo] | dfnsMin | dfnsFormat: 'EEE LLLL d yyyy' }}

{{ [dateOne, dateTwo] | dfnsMax | dfnsFormat: 'EEE LLLL d yyyy' }}

{{ dateThree | dfnsFormatDistanceToNow: options }} - (Explicit 'es'
locale)

{{ 0 | dfnsWeekdayName: 'full':options }} - (Explicit 'es' locale)

{{
'12 de Marzo'
| dfnsParse: parseFormat:parseDate:parseLocale
| dfnsFormat: 'MM/dd/yyyy'
}}


})
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.

$3

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

`typescript
// 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 }]
};
`

`typescript
// 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));
`

$3

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

> stackblitz example

`typescript
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:

{{ dateOne | dfnsFormat: 'EEE LLLL d yyyy' }}

---

Set default locale to: German,
Spanish.

})
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);
`

$3

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

- dfnsParse _(impure)_
- dfnsParsePure
- dfnsParseIso
- dfnsClosestTo
- dfnsMin
- dfnsMax

#### Format

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

- dfnsFormat _(impure)_
- dfnsFormatPure
- dfnsFormatRelative _(impure)_
- dfnsFormatRelativePure
- dfnsFormatDistance _(impure)_
- dfnsFormatDistancePure
- dfnsFormatDistanceStrict _(impure)_
- dfnsFormatDistanceStrictPure
- dfnsFormatDistanceToNow _(impure)_
- dfnsFormatDistanceToNowPure
- dfnsFormatDistanceToNowStrict _(impure)_
- dfnsFormatDistanceToNowStrictPure
- dfnsFormatDuration _(impure)_
- dfnsFormatDurationPure

#### Get

- dfnsGetOverlappingDaysInIntervals
- dfnsGetTime
- dfnsGetMilliseconds
- dfnsGetSeconds
- dfnsGetMinutes
- dfnsGetHours
- dfnsGetDate
- dfnsGetDayOfYear
- dfnsGetDay
- dfnsGetISODay
- dfnsGetISOWeek
- dfnsGetDaysInMonth
- dfnsGetMonth
- dfnsGetQuarter
- dfnsGetDaysInYear
- dfnsGetYear
- dfnsGetISOWeeksInYear
- dfnsGetISOWeekYear
- dfnsGetUnixTime
- dfnsGetWeek _(impure)_
- dfnsGetWeekPure
- dfnsGetWeekOfMonth _(impure)_
- dfnsGetWeekOfMonthPure
- dfnsGetWeeksInMonth _(impure)_
- dfnsGetWeeksInMonthPure
- dfnsGetDecade
- dfnsGetWeekYear _(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
- dfnsStartOfWeek _(impure)_
- dfnsStartOfWeekPure
- dfnsStartOfISOWeek
- dfnsStartOfMonth
- dfnsStartOfQuarter
- dfnsStartOfYear
- dfnsStartOfISOWeekYear
- dfnsStartOfDecade
- dfnsStartOfWeekYear _(impure)_
- dfnsStartOfWeekYearPure

#### Last Day Of

- dfnsLastDayOfWeek _(impure)_
- dfnsLastDayOfWeekPure
- dfnsLastDayOfISOWeek
- dfnsLastDayOfMonth
- dfnsLastDayOfQuarter
- dfnsLastDayOfYear
- dfnsLastDayOfISOWeekYear
- dfnsLastDayOfDecade

#### Is...?

- dfnsIsAfter
- dfnsIsBefore
- dfnsIsDate
- dfnsIsEqual
- dfnsIsFuture
- dfnsIsPast
- dfnsIsValid
- dfnsIsToday
- dfnsIsWeekend
- dfnsIsSameMonth
- dfnsIsSameYear
- dfnsIsExists
- dfnsIsFirstDayOfMonth
- dfnsIsFriday
- dfnsIsLastDayOfMonth
- dfnsIsLeapYear
- dfnsIsMatch _(impure)_
- dfnsIsMatchPure
- dfnsIsMonday
- dfnsIsSameDay
- dfnsIsSameHour
- dfnsIsSameISOWeekYear
- dfnsIsSameISOWeek
- dfnsIsSameMinute
- dfnsIsSameMonth
- dfnsIsSameQuarter
- dfnsIsSameSecond
- dfnsIsSameWeek
- dfnsIsSameWeekPure _(impure)_
- dfnsIsSameYear
- dfnsIsSaturday
- dfnsIsSunday
- dfnsIsThisHour
- dfnsIsThisISOWeek
- dfnsIsThisMinute
- dfnsIsThisMonth
- dfnsIsThisQuarter
- dfnsIsThisSecond
- dfnsIsThisWeek _(impure)_
- dfnsIsThisWeekPure
- dfnsIsThisYear
- dfnsIsThursday
- dfnsIsToday
- dfnsIsTomorrow
- dfnsIsTuesday
- dfnsIsWednesday
- dfnsIsWithinInterval
- dfnsIsYesterday

Utils

A collection of utilities built around date-fns functions.

$3

> 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().

$3

> 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

`html


{{ 0 | dfnsWeekdayName : 'x3' }}

``