https://github.com/philnash/time-formatter
A web component that converts a date time into your user's time zone and formats it locally.
https://github.com/philnash/time-formatter
Last synced: 6 months ago
JSON representation
A web component that converts a date time into your user's time zone and formats it locally.
- Host: GitHub
- URL: https://github.com/philnash/time-formatter
- Owner: philnash
- License: mit
- Created: 2020-09-16T14:01:37.000Z (about 5 years ago)
- Default Branch: main
- Last Pushed: 2021-03-02T11:17:45.000Z (over 4 years ago)
- Last Synced: 2025-03-13T06:23:23.501Z (7 months ago)
- Language: HTML
- Size: 16.6 KB
- Stars: 7
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
🕖🕗🕘🕙🕚 <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:
```bash
npm install @philnash/time-formatter
```
## About
`` relies on [`navigator.languages`](https://developer.mozilla.org/en-US/docs/Web/API/NavigatorLanguage/languages) to get a user's preferred language and [`Intl.DateTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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](https://philnash.github.io/time-formatter/example/). Two `` 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 `` custom element.
```javascript
import "@philnash/time-formatter";
```
If you want to use the `TimeFormatter` class directly, you can import it with:
```javascript
import { TimeFormatter } from "@philnash/time-formatter";
```
To use `` you will need a date time string in the format `YYYY-MM-DDTHH:mm:ss.sssZ` [as described in ecma262](https://tc39.es/ecma262/#sec-date-time-string-format). 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 `` to the page with a `datetime` attribute and default content:
```html
14/09/1984
```
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](https://tc39.es/proposal-intl-datetime-style/#sec-datetimeformat-abstracts).
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`:_
```html
14/09/1984
14/09/1984
14/09/1984
```
You can also pass the time zone name and language if you know your user's preference.
```html
14/09/1984
```
### 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