Intl.DateTimeFormat.prototype.formatToParts()

This is an experimental technology
Because this technology's specification has not stabilized, check the compatibility table for usage in various browsers. Also note that the syntax and behavior of an experimental technology is subject to change in future versions of browsers as the specification changes.

The Intl.DateTimeFormat.prototype.formatToParts() method allows locale-aware formatting of strings produced by DateTimeFormat formatters.

Syntax

JavaScript
Intl.DateTimeFormat.prototype.formatToParts(date)

Parameters

date Optional
The date to format.

Return value

An Array of objects containing the formatted date in parts.

Description

The formatToParts() method is useful for custom formatting of date strings. It returns an Array of objects containing the locale-specific tokens from which it possible to build custom strings while preserving the locale-specific parts. The structure the formatToParts() method returns, looks like this:

JavaScript
[
  { type: "day", value: "17" },
  { type: "weekday", value "Monday" }
]

Possible types are the following:

day
The string used for the day, for example "17".
dayPeriod
The string used for the day period, for example, "AM" or "PM".
era
The string used for the era, for example "BC" or "AD".
hour
The string used for the hour, for example "3" or "03".
literal
The string used for separating date and time values, for example one of " : , / ".
minute
The string used for the minute, for example "00".
month
The string used for the month, for example "12".
second
The string used for the second, for example "07" or "42".
timeZoneName
The string used for the name of the time zone, for example "UTC".
weekday
The string used for the weekday, for example "M", "Monday", or "Montag".
year
The string used for the year, for example "2012" or "96".

Examples

DateTimeFormat outputs localized, opaque strings that cannot be manipulated directly:

JavaScript
var date = Date.UTC(2012, 11, 17, 3, 0, 42);

var formatter = new Intl.DateTimeFormat("en-us", {
  weekday: 'long',
  year: 'numeric',
  month: 'numeric',
  day: 'numeric',
  hour: 'numeric',
  minute: 'numeric',
  second: 'numeric',
  hour12: true,
  timeZone: "UTC"
});

formatter.format(date);
// "Monday, 12/17/2012, 3:00:42 AM"

However, in many User Interfaces there is a desire to customize the formatting of this string. The formatToParts method enables locale-aware formatting of strings produced by DateTimeFormat formatters by providing you the string in parts:

JavaScript
formatter.formatToParts(date);

// return value: 
[ 
  { type: 'weekday',   value: 'Monday' }, 
  { type: 'literal',   value: ', '     }, 
  { type: 'month',     value: '12'     }, 
  { type: 'literal',   value: '/'      }, 
  { type: 'day',       value: '17'     }, 
  { type: 'literal',   value: '/'      }, 
  { type: 'year',      value: '2012'   }, 
  { type: 'literal',   value: ', '     }, 
  { type: 'hour',      value: '3'      }, 
  { type: 'literal',   value: ':'      }, 
  { type: 'minute',    value: '00'     }, 
  { type: 'literal',   value: ':'      }, 
  { type: 'second',    value: '42'     }, 
  { type: 'literal',   value: ' '      }, 
  { type: 'dayPeriod', value: 'AM'     } 
]

Now the information is available separately and it can be formatted and concatenated again in a customized way. For example by using Array.prototype.map(), arrow functions, a switch statement, template literals, and Array.prototype.reduce().

JavaScript
var dateString = formatter.formatToParts(date).map(({type, value}) => { 
  switch (type) {
    case 'dayPeriod': return `<strong>${value}</strong>`; 
    default : return value; 
  } 
}).reduce((string, part) => string + part);

This will make the day period bold, when using the formatToParts() method.

JavaScript
console.log(formatter.format(date));
// "Monday, 12/17/2012, 3:00:42 AM"

console.log(dateString);
// "Monday, 12/17/2012, 3:00:42 <strong>AM</strong>"

Specifications

Specification Status Comment
ECMAScript Internationalization API 4.0 (ECMA-402)
The definition of 'Intl.DateTimeFormat.prototype.formatToParts' in that specification.
Draft Not yet part of the draft specification. See issue #30 and PR #64. A Polyfill is available in this proposal repository.

Browser compatibility

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari (WebKit)
Basic support No support 51.0 (51.0)[1] No support No support No support
Feature Android Chrome for Android Firefox Mobile (Gecko) IE Phone Opera Mobile Safari Mobile
Basic support No support No support 51.0 (51.0)[2] No support No support No support

[1] This method was implemented in Gecko 51 (Firefox 51.0 / Thunderbird 51.0 / SeaMonkey 2.48) (see bug 1216150).

[2] This method was initially only exposed to B2G system apps starting from Gecko 46 (Firefox 46.0 / Thunderbird 46.0 / SeaMonkey 2.43) (see bug 1216150). In Gecko 51 (Firefox 51.0 / Thunderbird 51.0 / SeaMonkey 2.48) it was exposed to web content (see bug 1289340).

See also

License

© 2016 Mozilla Contributors
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-us/docs/web/javascript/reference/global_objects/datetimeformat/formattoparts

DateTimeFormat Internationalization Intl JavaScript Method Prototype