@philnash/time-formatter

🕖🕗🕘🕙🕚 <time-formatter> 🕐🕑🕒🕓🕔

A web component that converts a date time into your user's time zone and formats it locally.

Installation

Install the component with:

npm install @philnash/time-formatter

About

<time-formatter> relies on navigator.languages to get a user's preferred language and Intl.DateTimeFormat to convert and format a date time into a string. It brings the two features together into a web component that makes it easy to use and declarative.

Browser support

This requires support for:

• Custom elements - https://caniuse.com/custom-elementsv1
• NavigatorLanguage API - https://caniuse.com/mdn-api_navigatorlanguage_languages (falls back to navigator.language or navigator.userLanguage)
• Intl.DateTimeFormat.format - https://caniuse.com/mdn-javascript_builtins_intl_datetimeformat_format
• Intl.DateTimeFormat computed timeZone - https://caniuse.com/mdn-javascript_builtins_intl_datetimeformat_resolvedoptions_computed_timezone

Demo

You can see the element in action in this example here. Two <time-formatter> elements are used, one showing your time zone and one showing a time zone of your choice. You can choose the different levels for each of the formatting options and see how the date is formatted.

Usage

Import the @philnash/time-formatter module and that will register the <time-formatter> custom element.

import "@philnash/time-formatter";

If you want to use the TimeFormatter class directly, you can import it with:

import { TimeFormatter } from "@philnash/time-formatter";

To use <time-formatter> you will need a date time string in the format YYYY-MM-DDTHH:mm:ss.sssZ as described in ecma262. In the initial version of this component, Date.parse is used to parse this string and non-standard date time strings can be parsed differently by different browsers.

Add the <time-formatter> to the page with a datetime attribute and default content:

<time-formatter datetime="1984-09-14T01:36:00.000+01:00"
  >14/09/1984</time-formatter
>

The default content will be replaced with the result of parsing the datetime attribute, and formatted according to the user's local time zone and language settings using Intl.DateTimeFormat. You can provide options for how the time is formatted and the default is the default used by Intl.DateTimeFormat, which is just the date. If the user's preferred language is set to en-GB the above example would be rendered as 14/09/1984 and if the preferred language is en-US then it would be rendered as 09/14/1984.

You can pass options for each component of the date time to describe how it should be rendered. The options are listed here.

So, taking the above datetime and passing different formatting options you may get the following results:

Note my current prefered language is en-GB and my current time zone is Australia/Melbourne:

<time-formatter datetime="1984-09-14T01:36:00.000+01:00" year="numeric"
  >14/09/1984</time-formatter
>
<!-- 1984 -->
<time-formatter
  datetime="1984-09-14T01:36:00.000+01:00"
  hour="numeric"
  minute="numeric"
  second="numeric"
  >14/09/1984</time-formatter
>
<!-- 10:36:00 -->
<time-formatter
  datetime="1984-09-14T01:36:00.000+01:00"
  era="short"
  year="numeric"
  month="long"
  weekday="long"
  day="numeric"
  hour="numeric"
  minute="numeric"
  second="numeric"
  time-zone-name="long"
  >14/09/1984</time-formatter
>
<!-- Friday, 14 September 1984 AD, 10:36:00 Australian Eastern Standard Time -->

You can also pass the time zone name and language if you know your user's preference.

<time-formatter
  datetime="1984-09-14T01:36:00.000+01:00"
  era="short"
  year="numeric"
  month="long"
  weekday="long"
  day="numeric"
  hour="numeric"
  minute="numeric"
  second="numeric"
  time-zone-name="long"
  >14/09/1984</time-formatter
>
<!-- vendredi 14 septembre 1984 ap. J.-C. à 02:36:00 heure d’été d’Europe centrale -->

Errors/fallbacks

If the datetime cannot be parsed or any other error occurs in trying to calculate or format the date, then the default child content will remain. An error will be logged to the console.

TODO

• Feedback
• npm package and install instructions
• Live example
• Tests

LICENSE

MIT (c) 2020 Phil Nash