A comprehensive, typed dataset of IANA timezone identifiers with metadata. This library provides a complete list of IANA timezone names along with their standard UTC offsets, common abbreviations, and regions. Perfect for datetime pickers, global dashboards, scheduling apps, and localization engines.
- 📦 Zero runtime dependencies
- 🔍 Complete IANA timezone dataset
- 📝 TypeScript-first with full type definitions
- 🎯 Utility functions for timezone operations
- 🌐 Support for both ESM and CommonJS
- 📊 Includes standard offsets and abbreviations
- 🧪 Thoroughly tested with Vitest
npm install timezone-codesimport { timezones, getTimezoneByName } from 'timezone-codes';
// Access the complete timezone list
console.log(timezones);
// Get a specific timezone
const newYork = getTimezoneByName('America/New_York');
console.log(newYork);
// {
// name: 'America/New_York',
// standardUtcOffset: '-05:00',
// standardAbbreviation: 'EST',
// region: 'America'
// }The package includes a CLI tool that can be used to quickly look up timezone information:
npx timezone-codes America/New_YorkOutput:
Timezone: America/New_York
Region: America
Standard UTC Offset: -05:00
Standard Abbreviation: EST
Current UTC Offset: -04:00
Current Abbreviation: EDT
import {
getTimezonesByRegion,
getStandardUtcOffset,
isValidTimezoneName,
getCurrentTimezoneDetails,
} from 'timezone-codes';
// Get all timezones in a region
const europeTimezones = getTimezonesByRegion('Europe');
console.log(europeTimezones);
// Get standard UTC offset
const offset = getStandardUtcOffset('Asia/Tokyo');
console.log(offset); // '+09:00'
// Check if a timezone name is valid
const isValid = isValidTimezoneName('America/New_York');
console.log(isValid); // true
// Get current timezone details (including DST)
const details = await getCurrentTimezoneDetails('America/New_York');
console.log(details);
// {
// currentUtcOffset: '-04:00', // During DST
// currentAbbreviation: 'EDT' // During DST
// }type IANATimezoneName = string; // e.g., 'America/New_York'
type TimezoneAbbreviation = string; // e.g., 'EST', 'JST'
type UTCOffset = string; // e.g., '-05:00', '+09:00'
type TimezoneRegion = string; // e.g., 'America', 'Asia'
interface Timezone {
name: IANATimezoneName;
standardUtcOffset: UTCOffset;
standardAbbreviation: TimezoneAbbreviation;
region: TimezoneRegion;
}
interface CurrentTimezoneDetails {
currentUtcOffset: UTCOffset;
currentAbbreviation: TimezoneAbbreviation;
}The complete list of timezones with their metadata. This is a readonly array to prevent accidental modifications.
Gets a timezone by its IANA name. Returns undefined if not found.
Gets all timezones in a specific region. Case-insensitive. Returns an empty array if no timezones found.
Gets the standard UTC offset for a timezone. Returns undefined if not found.
Checks if a string is a valid IANA timezone name.
Gets the current timezone details including DST information. Returns undefined if the timezone is invalid.
The timezone data is sourced from the IANA Time Zone Database and processed to include standard offsets and common abbreviations. The data is embedded directly in the library, ensuring zero runtime dependencies.
Contributions are welcome! Please feel free to submit a Pull Request.
This package follows Semantic Versioning (SemVer).
- Patch releases (1.0.x): Bug fixes and minor updates that don't change the API
- Minor releases (1.x.0): New features added in a backward-compatible manner
- Major releases (x.0.0): Breaking changes to the API
The package is published to npm automatically through GitHub Actions when a new version tag is pushed. For more detailed information about the release process, see RELEASING.md.
MIT