date-fns-timezone
utm_content=prantlf/date-fns-timezone&utm_campaign=Badge_Grade)
Provides parsing and formatting date strings and time zone conversions supporting IANA time zones. Date parsing, formatting and other queries and manipulations are provided by date-fns. List of canonical time zone names and time zone conversions are provided by timezone-support.
Synopsis
const { listTimeZones } = require('timezone-support')
const { parseFromTimeZone, formatToTimeZone } = require('date-fns-timezone')
const timeZones = listTimeZones()
const date = parseFromTimeZone('2018-09-01 18:01:36.386', { timeZone: 'Europe/Berlin' })
const date = new Date('2018-09-01Z16:01:36.386Z')
const format = 'D.M.YYYY HH:mm:ss.SSS [GMT]Z (z)'
const output = formatToTimeZone(date, format, { timeZone: 'Europe/Berlin' })
Installation and Loading
This module can be installed in your project using NPM or Yarn. Make sure, that you use Node.js version 6 or newer.
$ npm i date-fns-timezone --save
$ yarn add date-fns-timezone
Specific Environments
Load the main module in an application using CommonJS modules:
const {
convertToLocalTime, convertToTimeZone, parseFromTimeZone, formatToTimeZone
} = require('date-fns-timezone')
Load only specific modules in an application using CommonJS modules:
const { convertToLocalTime } = require('date-fns-timezone/dist/convertToLocalTime')
const { convertToTimeZone } = require('date-fns-timezone/dist/convertToTimeZone')
const { parseFromTimeZone } = require('date-fns-timezone/dist/parseFromTimeZone')
const { formatToTimeZone } = require('date-fns-timezone/dist/formatToTimeZone')
Load the main module in an application using ES6 modules:
import {
convertToLocalTime, convertToTimeZone, parseFromTimeZone, formatToTimeZone
} from './node_modules/date-fns-timezone/src/index.js'
Load only specific modules in an application using ES6 modules:
import { convertToLocalTime } from './node_modules/date-fns-timezone/src/convertToLocalTime.js'
import { convertToTimeZone } from './node_modules/date-fns-timezone/src/convertToTimeZone.js'
import { parseFromTimeZone } from './node_modules/date-fns-timezone/src/parseFromTimeZone.js'
import { formatToTimeZone } from './node_modules/date-fns-timezone/src/formatToTimeZone.js'
Load the main module in the browser with plain JavaScript:
<script src="https://cdnjs.cloudflare.com/ajax/libs/date-fns/1.29.0/date_fns.min.js"></script>
<script src="https://unpkg.com/timezone-support@1.2.1/dist/index.umd.js"></script>
<script src="https://unpkg.com/date-fns-timezone@0.0.1/dist/index.umd.js"></script>
<script>
(() => {
const {
convertToLocalTime, convertToTimeZone, parseFromTimeZone, formatToTimeZone
} = window.dateFnsTimezone
})()
</script>
Load the main module in the browser with RequireJS:
<script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/date-fns/1.29.0/date_fns.min.js"></script>
<script src="https://unpkg.com/timezone-support@1.2.1/dist/index.umd.js"></script>
<script src="https://unpkg.com/date-fns-timezone@0.0.1/dist/index.umd.js"></script>
<script>
require(['date-fns-timezone'], ({ parseFromTimeZone, formatToTimeZone }) => {
})
</script>
Usage Scenarios
The minimal, but powerful API of this module provides functionality for the most usual usage scenarios in your web applications.
List all available time zones
Users may need to choose the time zone, which they want to see and enter dates in. Time zones can be listed in a dropdown for the user to choose from, for example.
const { listTimeZones } = require('timezone-support')
const timeZones = listTimeZones()
See the function listTimeZones for more information.
Parse a date from a string in a specific time zone
Dates are usually entered in a time zone chosen by the user, but they are supposed to be stored in UTC. After the user input is parsed, the result date needs to be converted from the user time zone to the native Date
object, which maintains the date in the browser-local time zone and UTC.
const { parseZonedTime } = require('date-fns-timezone/dist/parseFromTimeZone')
const enteredTime = '2018-09-02 12:04:30.982'
const timeZone = 'Europe/Berlin'
const storedDate = parseFromTimeZone(enteredTime, { timeZone })
See the function parseFromTimeZone for more information.
Format a date to a string in specific time zone
Dates are supposed to be stored in UTC, but they are usually displayed in a time zone chosen by the user. Before the date value is formatted, it needs to be converted to the user time zone.
const { formatToTimeZone } = require('date-fns-timezone/dist/formatToTimeZone')
const storedDate = new Date('2018-09-02T10:04:30.982Z')
const format = 'D.M.YYYY H:mm:ss [GMT]Z (z)'
const timeZone = 'Europe/Berlin'
const displayedTime = formatToTimeZone(storedDate, format, { timeZone })
See the function formatToTimeZone for more information.
Change the time zone of date
Date pickers usually supply the date, which the user selected, and the time zone is implied from the user settings. The local time in the date value is not the browser-local time and the UTC value cannot be used yet. The date has to be converted from the user time zone to the browser-local time to become valid.
const { convertToLocalTime } = require('date-fns-timezone/dist/convertToLocalTime')
const chosenDate = new Date(2018, 8, 2, 12, 4, 30, 982)
const timeZone = 'Europe/Berlin'
const storedDate = convertToLocalTime(chosenDate, { timeZone })
Date pickers are usually initialized by a date in the time zone implied from the user settings. However, the browser-local time may be different. The date has to be converted from the browser-local time to the user time zone.
const { convertToTimeZone } = require('date-fns-timezone/dist/convertToTimeZone')
const storedDate = new Date('2018-09-02T10:04:30.982Z')
const timeZone = 'Europe/Berlin'
const defaultDate = convertToTimeZone(storedDate, { timeZone })
See functions convertToLocalTime and convertToTimeZone for more information.
API Reference
The API consists of functions only. They are divided to three modules, which you can load separately or together depending on your usage scenario.
date-fns-timezone/dist/index
Main package module for Node.js application. CommonJS format. Includes all functions from the other modules.
date-fns-timezone/dist/index.umd.js
Main package module first of all for web browsers. UMD format, minified. Includes all functions from the other modules. Make sure, that you include script
elements for date-fns
and timezone-support
on your web page before this one as documented earlier.
convertToLocalTime
convertToTimeZone
parseFromTimeZone
formatToTimeZone
Contributing
In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.
Release History
- 2018-09-17 v0.0.1 Initial release
License
Copyright (c) 2018 Ferdinand Prantl
Licensed under the MIT license.