@vvo/tzdb

When building a time zone selection UI and saving the selection to a database:

1. Save the name attribute (e.g., America/Los_Angeles) in your database.
2. Handle grouped values during retrieval: When displaying a default value from your database, ensure you match either the exact name or any name within the group array to ensure the correct time zone is selected in the UI.

const value = timeZones.find((timeZone) => {
  return dbData.timeZone === timeZone.name || timeZone.group.includes(dbData.timeZone);
});

Import the available functions and data arrays from the @vvo/tzdb package.

import { getTimeZones, rawTimeZones, timeZonesNames, abbreviations } from "@vvo/tzdb";

To use the tzdb library in your project, install the @vvo/tzdb package using npm.

npm add @vvo/tzdb

The getTimeZones() method returns an array of time zone objects. Because time zone offsets change based on Daylight Saving Time (DST), this is a method called at runtime to ensure accuracy.

By default, it returns time zones with their current offsets. You can optionally include UTC by passing { includeUtc: true }.

const timeZones = getTimeZones();

// Include UTC in the result
const timeZonesWithUtc = getTimeZones({ includeUtc: true });

A simple array of all existing raw IANA time zone names (e.g., "America/Los_Angeles").

[
  "America/Juneau",
  "America/Kentucky/Louisville",
  "America/Kentucky/Monticello",
  // ...
];

An object mapping full time zone names to their abbreviations (e.g., "Australian Central Daylight Time": "ACDT").

Caution: Abbreviations can be ambiguous (e.g., CST can refer to Central Standard Time, China Standard Time, or Cuba Standard Time). These abbreviations do not directly map to properties in the time zone objects returned by getTimeZones() or rawTimeZones().

{
  "Australian Central Daylight Time": "ACDT",
  "Australian Central Standard Time": "ACST",
  // ...
};

Each object returned by getTimeZones() contains detailed information about a time zone, including its IANA name, alternative name, grouping, and current offsets.

[
  {
    name: "America/Los_Angeles",
    alternativeName: "Pacific Time",
    group: ["America/Los_Angeles"],
    continentCode: "NA",
    continentName: "North America",
    countryName: "United States",
    countryCode: "US",
    mainCities: ["Los Angeles", "San Diego", "San Jose", "San Francisco"],
    rawOffsetInMinutes: -480,
    abbreviation: "PST",
    rawFormat: "-08:00 Pacific Time - Los Angeles, San Diego, San Jose, San Francisco",
    currentTimeOffsetInMinutes: -420,
    currentTimeFormat: "-07:00 Pacific Time - Los Angeles, San Diego",
  },
  // ...
];

An array of time zone objects that includes all metadata (name, alternativeName, group, etc.) but excludes the currentTimeOffsetInMinutes and currentTimeFormat properties. This is useful when you do not need runtime-sensitive offset information.

[
  {
    name: "America/Los_Angeles",
    alternativeName: "Pacific Time",
    group: ["America/Los_Angeles"],
    continentCode: "NA",
    continentName: "North America",
    countryName: "United States",
    countryCode: "US",
    mainCities: ["Los Angeles", "San Diego", "San Jose", "San Francisco"],
    rawOffsetInMinutes: -480,
    abbreviation: "PST",
    rawFormat: "-08:00 Pacific Time - Los Angeles, San Diego, San Jose, San Francisco",
  },
  // ...
];

The abbreviations export provides access to time zone abbreviations as defined in the abbreviations.json source file.

import { abbreviations } from '@vvo/tzdb';

console.log(abbreviations);

The timeZonesNames export provides a mapping or list of time zone names as defined in the time-zones-names.json source file.

import { timeZonesNames } from '@vvo/tzdb';

console.log(timeZonesNames);

The rawTimeZones export provides direct access to the underlying time zone data as defined in the raw-time-zones.json source file.

import { rawTimeZones } from '@vvo/tzdb';

console.log(rawTimeZones);