@angular/common

DatePipe

pipe

Formats a date value according to locale rules.

class DatePipe {
}

Formats a date value according to locale rules.

DatePipe is executed only when it detects a pure change to the input value. A pure change is either a change to a primitive input value (such as String, Number, Boolean, or Symbol), or a changed object reference (such as Date, Array, Function, or Object).

Note that mutating a Date object does not cause the pipe to be rendered again. To ensure that the pipe is executed, you must create a new Date object.

Only the en-US locale data comes with Angular. To localize dates in another language, you must import the corresponding locale data. See the I18n guide for more information.

The time zone of the formatted value can be specified either by passing it in as the second parameter of the pipe, or by setting the default through the DATE_PIPE_DEFAULT_OPTIONS injection token. The value that is passed in as the second parameter takes precedence over the one defined using the injection token.

The result of this pipe is not reevaluated when the input is mutated. To avoid the need to reformat the date on every change-detection cycle, treat the date as an immutable object and change the reference when the pipe needs to run again.

Pre-defined format options

Option	Equivalent to	Examples (given in `en-US` locale)
`'short'`	`'M/d/yy, h:mm a'`	`6/15/15, 9:03 AM`
`'medium'`	`'MMM d, y, h:mm:ss a'`	`Jun 15, 2015, 9:03:01 AM`
`'long'`	`'MMMM d, y, h:mm:ss a z'`	`June 15, 2015 at 9:03:01 AM GMT+1`
`'full'`	`'EEEE, MMMM d, y, h:mm:ss a zzzz'`	`Monday, June 15, 2015 at 9:03:01 AM GMT+01:00`
`'shortDate'`	`'M/d/yy'`	`6/15/15`
`'mediumDate'`	`'MMM d, y'`	`Jun 15, 2015`
`'longDate'`	`'MMMM d, y'`	`June 15, 2015`
`'fullDate'`	`'EEEE, MMMM d, y'`	`Monday, June 15, 2015`
`'shortTime'`	`'h:mm a'`	`9:03 AM`
`'mediumTime'`	`'h:mm:ss a'`	`9:03:01 AM`
`'longTime'`	`'h:mm:ss a z'`	`9:03:01 AM GMT+1`
`'fullTime'`	`'h:mm:ss a zzzz'`	`9:03:01 AM GMT+01:00`

Custom format options

You can construct a format string using symbols to specify the components of a date-time value, as described in the following table. Format details depend on the locale. Fields marked with (*) are only available in the extra data set for the given locale.

Field type	Format	Description	Example Value
Era	G, GG & GGG	Abbreviated	AD
	GGGG	Wide	Anno Domini
	GGGGG	Narrow	A
Year	y	Numeric: minimum digits	2, 20, 201, 2017, 20173
	yy	Numeric: 2 digits + zero padded	02, 20, 01, 17, 73
	yyy	Numeric: 3 digits + zero padded	002, 020, 201, 2017, 20173
	yyyy	Numeric: 4 digits or more + zero padded	0002, 0020, 0201, 2017, 20173
ISO Week-numbering year	Y	Numeric: minimum digits	2, 20, 201, 2017, 20173
	YY	Numeric: 2 digits + zero padded	02, 20, 01, 17, 73
	YYY	Numeric: 3 digits + zero padded	002, 020, 201, 2017, 20173
	YYYY	Numeric: 4 digits or more + zero padded	0002, 0020, 0201, 2017, 20173
Month	M	Numeric: 1 digit	9, 12
	MM	Numeric: 2 digits + zero padded	09, 12
	MMM	Abbreviated	Sep
	MMMM	Wide	September
	MMMMM	Narrow	S
Month standalone	L	Numeric: 1 digit	9, 12
	LL	Numeric: 2 digits + zero padded	09, 12
	LLL	Abbreviated	Sep
	LLLL	Wide	September
	LLLLL	Narrow	S
ISO Week of year	w	Numeric: minimum digits	1... 53
	ww	Numeric: 2 digits + zero padded	01... 53
Week of month	W	Numeric: 1 digit	1... 5
Day of month	d	Numeric: minimum digits	1
	dd	Numeric: 2 digits + zero padded	01
Week day	E, EE & EEE	Abbreviated	Tue
	EEEE	Wide	Tuesday
	EEEEE	Narrow	T
	EEEEEE	Short	Tu
Week day standalone	c, cc	Numeric: 1 digit	2
	ccc	Abbreviated	Tue
	cccc	Wide	Tuesday
	ccccc	Narrow	T
	cccccc	Short	Tu
Period	a, aa & aaa	Abbreviated	am/pm or AM/PM
	aaaa	Wide (fallback to `a` when missing)	ante meridiem/post meridiem
	aaaaa	Narrow	a/p
Period*	B, BB & BBB	Abbreviated	mid.
	BBBB	Wide	am, pm, midnight, noon, morning, afternoon, evening, night
	BBBBB	Narrow	md
Period standalone*	b, bb & bbb	Abbreviated	mid.
	bbbb	Wide	am, pm, midnight, noon, morning, afternoon, evening, night
	bbbbb	Narrow	md
Hour 1-12	h	Numeric: minimum digits	1, 12
	hh	Numeric: 2 digits + zero padded	01, 12
Hour 0-23	H	Numeric: minimum digits	0, 23
	HH	Numeric: 2 digits + zero padded	00, 23
Minute	m	Numeric: minimum digits	8, 59
	mm	Numeric: 2 digits + zero padded	08, 59
Second	s	Numeric: minimum digits	0... 59
	ss	Numeric: 2 digits + zero padded	00... 59
Fractional seconds	S	Numeric: 1 digit	0... 9
	SS	Numeric: 2 digits + zero padded	00... 99
	SSS	Numeric: 3 digits + zero padded (= milliseconds)	000... 999
Zone	z, zz & zzz	Short specific non location format (fallback to O)	GMT-8
	zzzz	Long specific non location format (fallback to OOOO)	GMT-08:00
	Z, ZZ & ZZZ	ISO8601 basic format	-0800
	ZZZZ	Long localized GMT format	GMT-8:00
	ZZZZZ	ISO8601 extended format + Z indicator for offset 0 (= XXXXX)	-08:00
	O, OO & OOO	Short localized GMT format	GMT-8
	OOOO	Long localized GMT format	GMT-08:00

Format examples

These examples transform a date into various formats, assuming that dateObj is a JavaScript Date object for year: 2015, month: 6, day: 15, hour: 21, minute: 43, second: 11, given in the local time for the en-US locale.

          
            {{ dateObj | date }}               // output is 'Jun 15, 2015'{{ dateObj | date:'medium' }}      // output is 'Jun 15, 2015, 9:43:11 PM'{{ dateObj | date:'shortTime' }}   // output is '9:43 PM'{{ dateObj | date:'mm:ss' }}       // output is '43:11'{{ dateObj | date:"MMM dd, yyyy 'at' hh:mm a" }}  // output is 'Jun 15, 2015 at 09:43 PM'

Usage example

The following component uses a date pipe to display the current date in different formats.

          
            @Component({ selector: 'date-pipe', template: `<div>   <p>Today is {{today | date}}</p>   <p>Or if you prefer, {{today | date:'fullDate'}}</p>   <p>The time is {{today | date:'h:mm a z'}}</p> </div>`})// Get the current date and time as a date-time value.export class DatePipeComponent {  today: number = Date.now();}

transform

3 overloads

@paramvaluestring | number | Date

The date expression: a Date object, a number (milliseconds since UTC epoch), or an ISO string (https://www.w3.org/TR/NOTE-datetime).

@paramformatstring

The date/time components to include, using predefined options or a custom format string. When not provided, the DatePipe looks for the value using the DATE_PIPE_DEFAULT_OPTIONS injection token (and reads the dateFormat property). If the token is not configured, the mediumDate is used as a value.

@paramtimezonestring

A timezone offset (such as '+0430'), or a standard UTC/GMT, or continental US timezone abbreviation. When not provided, the DatePipe looks for the value using the DATE_PIPE_DEFAULT_OPTIONS injection token (and reads the timezone property). If the token is not configured, the end-user's local system timezone is used as a value.

@paramlocalestring

A locale code for the locale format rules to use. When not supplied, uses the value of LOCALE_ID, which is en-US by default. See Setting your app locale.

@returnsstring

@paramvaluenull

@paramformatstring

@paramtimezonestring

@paramlocalestring

@returnsnull

@paramvaluestring | number | Date

@paramformatstring

@paramtimezonestring

@paramlocalestring

@returnsstring