PackagesIso localeTimezones

Timezones

Working with IANA timezone identifiers and country-timezone mappings.

Last updated:

Timezones

@visulima/iso-locale provides comprehensive IANA timezone database mappings, allowing you to find timezones for countries and countries for timezones.

Getting Timezones

By Country

import { getTimezonesByCountry, getPrimaryTimezone } from "@visulima/iso-locale";

// Get all timezones for a country
const timezones = getTimezonesByCountry("US");
console.log(timezones);
// ["America/New_York", "America/Los_Angeles", "America/Chicago", ...]

// Get primary timezone (first in list)
const primary = getPrimaryTimezone("US");
console.log(primary); // "America/Adak"

Single Timezone Countries

import { getTimezonesByCountry } from "@visulima/iso-locale";

getTimezonesByCountry("GB"); // ["Europe/London"]
getTimezonesByCountry("FR"); // ["Europe/Paris"]
getTimezonesByCountry("JP"); // ["Asia/Tokyo"]

Multi-Timezone Countries

import { getTimezonesByCountry } from "@visulima/iso-locale";

// United States has many timezones
getTimezonesByCountry("US").length; // 29 timezones

// Canada has many timezones
getTimezonesByCountry("CA").length; // 27 timezones

// Australia has multiple timezones
getTimezonesByCountry("AU");
// ["Australia/Adelaide", "Australia/Brisbane", "Australia/Sydney", ...]

// Russia has many timezones
getTimezonesByCountry("RU").length; // 26 timezones

Finding Countries by Timezone

import { getCountriesForTimezone } from "@visulima/iso-locale";

// Find countries using a specific timezone
const countries = getCountriesForTimezone("Europe/London");
console.log(countries); // ["GB", ...]

const countries2 = getCountriesForTimezone("America/New_York");
console.log(countries2); // ["US"]

All Timezones

import { all as timezonesAll } from "@visulima/iso-locale";

const allTimezones = timezonesAll();
console.log(allTimezones.length); // 400+ timezones
console.log(allTimezones);
// ["Africa/Abidjan", "Africa/Accra", ...] (sorted)

Validation

import { isValidTimezone } from "@visulima/iso-locale";

isValidTimezone("Europe/London"); // true
isValidTimezone("America/New_York"); // true
isValidTimezone("Invalid/Timezone"); // false

Indexed Access

For fast lookups, use the indexed map:

import { timezonesByCountry } from "@visulima/iso-locale";

const timezones = timezonesByCountry["US"];
console.log(timezones); // readonly array of timezones

Examples

Get Primary Timezone for Country

import { getPrimaryTimezone } from "@visulima/iso-locale";

function getCountryTimezone(countryCode: string) {
    return getPrimaryTimezone(countryCode);
}

getCountryTimezone("US"); // "America/Adak"
getCountryTimezone("GB"); // "Europe/London"

Find Countries in Same Timezone

import { getCountriesForTimezone, getTimezonesByCountry } from "@visulima/iso-locale";

function getCountriesInSameTimezone(countryCode: string) {
    const timezones = getTimezonesByCountry(countryCode);
    if (timezones.length === 0) return [];

    // Get countries for the primary timezone
    return getCountriesForTimezone(timezones[0]);
}

Validate Timezone Before Use

import { isValidTimezone } from "@visulima/iso-locale";

function safeTimezoneOperation(timezone: string) {
    if (!isValidTimezone(timezone)) {
        throw new Error(`Invalid timezone: ${timezone}`);
    }

    // Use timezone with date libraries like date-fns, dayjs, etc.
    // Example with date-fns-tz:
    // import { zonedTimeToUtc } from "date-fns-tz";
    // return zonedTimeToUtc(new Date(), timezone);
}

List All Countries with Timezones

import { getCountriesWithTimezones } from "@visulima/iso-locale";

const countries = getCountriesWithTimezones();
console.log(countries.length); // 200+ countries

Next Steps

Support

Contribute to our work and keep us going

Community is the heart of open source. The success of our packages wouldn't be possible without the incredible contributions of users, testers, and developers who collaborate with us every day.Want to get involved? Here are some tips on how you can make a meaningful impact on our open source projects.

Ready to help us out?

Be sure to check out the package's contribution guidelines first. They'll walk you through the process on how to properly submit an issue or pull request to our repositories.

Submit a pull request

Found something to improve? Fork the repo, make your changes, and open a PR. We review every contribution and provide feedback to help you get merged.

Good first issues

Simple issues suited for people new to open source development, and often a good place to start working on a package.
View good first issues