@bigbinary/neeto-time-zones

A simple and lightweight NPM package for working with time zones. This package provides a human friendly timezone selector and utility functions for timezones.

Installation

You can install the package using yarn:

yarn add @bigbinary/neeto-time-zones

Importing CSS styles to the main stylesheet

You should add the following to main.scss file:

@import "@bigbinary/neeto-time-zones/dist/style.css";

NeetoTimezoneSelector

Check out the live demo

Usage 1

import { NeetoTimezoneSelector } from "@bigbinary/neeto-time-zones";

const ReactComponent = () => {
  const timezoneRef = useCallback(node => {
    if (!(node !== null)) return;

    new NeetoTimezoneSelector(node, {
      elementId: "custom-selector-element",
      className: "custom-selector-class",
      initialValue: "initial-timezone",
      position: "top",
      onChange: (timezone) => {
        console.log(timezone);
      },
      onHourFormatChange: (timeFormat) => {
        console.log(timeFormat);
      }
    });
  }, []);

  return (
    <div
      ref={timezoneRef}
    />
  );
};

Usage 2

import NeetoTimezoneSelector from "@bigbinary/neeto-time-zones/react";

const ReactComponent = () => {
  return (
    <NeetoTimezoneSelector
      elementId="custom-selector-element"
      className="custom-selector-class"
      initialValue="initial-timezone"
      position="top"
      onChange={(timezone) => {
        console.log(timezone);
      }}
      onHourFormatChange={(timeFormat) => {
        console.log(timeFormat);
      }}
    />
  );
}

Configuration

You can pass options as the second parameter to configure the timezone selector component.

1. elementId: ID for the NeetoTimezoneSelector. By default the ID will be timezone-selector
2. className: Custom classes that can be added to the component.
3. initialValue: Initial Value of the timezone selector.
4. position: Position in which the selector should open in. Available options: top, bottom. Default position is bottom.
5. onChange: Function to be called when the timezone selector changes.
6. onHourFormatChange: Function to be called when the time format changes.
7. isTimeFormatSwitchVisible: Setting this to false will hide the time format toggle. The default value is true.
8. isTimeFormat24H: When the internal time format toggle is disabled, use this prop to pass the time format option. This will be used to change the time format inside the timezone selector.

ianaTimezoneToHumanReadable

import { ianaTimezoneToHumanReadable } from "@bigbinary/neeto-time-zones";

ianaTimezoneToHumanReadable("Asia/Calcutta") // => Indian Standard Time

ianaTimezoneToHumanReadable("America/New_York") // => Eastern Standard Time

ianaTimezoneToHumanReadable("Europe/Berlin") // => Central Standard Time

Transliteration support

Timezone labels can be displayed in the user's browser language script (e.g., Hindi, Arabic, Japanese). This is transliteration — the English timezone names are written phonetically in the target script, not translated.

The picker widget automatically detects the browser locale via navigator.language and loads the appropriate transliteration file. No configuration is needed for the picker.

For consuming apps that use ianaTimezoneToHumanReadable directly (without rendering the picker), call initTranslations() once at app startup to pre-load the transliteration data:

import { initTranslations } from "@bigbinary/neeto-time-zones";

// Call once at app startup (e.g., in your entry point)
initTranslations();

// After initTranslations resolves, ianaTimezoneToHumanReadable
// returns transliterated labels based on the browser locale.
ianaTimezoneToHumanReadable("Asia/Calcutta")
// => "इंडियन स्टैंडर्ड टाइम" (when browser locale is "hi")
// => "Indian Standard Time" (when browser locale is "en" or unsupported)

Supported locales (35)

ar, bg, ca, cs, da, de, es, es-MX, et, fi, fil, fr, he, hi, hr, hu, id, it, ja, ko, nl, pl, pt, pt-BR, ro, ru, sk, sl, sv, th, tr, uk, vi, zh-CN, zh-TW

Chinese locale variants are handled automatically:

• zh-Hans-CN, zh-Hans, zh-SG, zh → Simplified Chinese (zh-CN)
• zh-Hant-TW, zh-Hant, zh-HK, zh-MO → Traditional Chinese (zh-TW)

Adding a new locale

1. Create data/translations/<locale>.json with the required structure (see existing files for reference)
2. Copy the file to ruby/data/translations/<locale>.json
3. Add a case "<locale>": return () => import("../../data/translations/<locale>.json"); entry in js/translations/index.js
4. Rebuild the package

getTimezoneObject

import { getTimezoneObject } from "@bigbinary/neeto-time-zones";

getTimezoneObject("Asia/Kolkata")
// => { utc: ["Asia/Kolkata", "Asia/Calcutta"], main: "Asia/Kolkata", label: "Indian Standard Time", ... }

isValidTimezone

import { isValidTimezone } from "@bigbinary/neeto-time-zones";

isValidTimezone("Asia/Kolkata") // => true
isValidTimezone("Invalid/Zone") // => false

getBrowserTimezone

import { getBrowserTimezone } from "@bigbinary/neeto-time-zones";

getBrowserTimezone() // => "Asia/Kolkata" (based on browser's Intl API)

Development

Clone the repo

git clone [email protected]:bigbinary/neeto-time-zones.git
cd neeto-time-zones/js
yarn install
yarn dev

To bundle with host app:

yarn build && cp dist/* ../../neeto-cal-web/node_modules/@bigbinary/neeto-time-zones/dist

Instructions for Publishing

A package is released upon merging a PR labeled as patch, minor, or major into the main branch. The patch label addresses bug fixes, minor signifies the addition of new features, and major denotes breaking changes, adhering to the principles outlined in Semantic Versioning (SemVer).

You can checkout the Create and publish releases workflow in GitHub Actions to get a live update.