# timezone-groups

> A JavaScript library to group time zones based on offset (DST-aware), name or region.

Latest version **1.0.1** (published 2026-09-22) · MIT license · 0 weekly downloads

## Install

```sh
npm install timezone-groups
pnpm add timezone-groups
yarn add timezone-groups
bun add timezone-groups
```

## Health

**Score 60/100 (C)** — status: active.

Positive: esm support; no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types.

## Facts

| | |
|---|---|
| Version | 1.0.1 |
| Published | 2026-09-22 |
| First published | 2023-09-25 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM |
| Dependencies | 1 |
| Unpacked size | 29.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | JC Franco |
| Maintainers | jcfranco |

## Links

- npm: https://www.npmjs.com/package/timezone-groups
- Repository: https://github.com/jcfranco/timezone-groups
- Homepage: https://github.com/jcfranco/timezone-groups#readme
- Issues: https://github.com/jcfranco/timezone-groups/issues
- npm.io page: https://npm.io/package/timezone-groups

## Dependencies (1)

- [countries-and-timezones](https://npm.io/package/countries-and-timezones.md) ^3.9.0

## Recent versions

- 1.0.1 (latest) — 2026-09-22
- 1.0.0 — 2026-05-05
- 0.10.4 — 2024-12-03
- 0.10.3 — 2024-12-03
- 0.10.2 — 2024-09-24
- 0.10.1 — 2024-09-24
- 0.10.0 — 2024-09-18
- 0.9.1 — 2024-08-13
- 0.9.0 — 2024-07-29
- 0.8.0 — 2023-10-11
- 0.7.0 — 2023-10-06
- 0.6.0 — 2023-10-03
- 0.5.0 — 2023-10-03
- 0.4.0 — 2023-10-03
- 0.3.0 — 2023-10-02
- … 2 more at https://npm.io/package/timezone-groups/versions

## README

# Timezone Groups

![npm](https://img.shields.io/npm/v/timezone-groups)

`timezone-groups` is a versatile NPM package that allows you to effortlessly generate timezone groups in both Node.js and browser environments. It supports multiple date libraries, including the option to create and use custom ones.

## Features

- Compatible with Node.js and the latest two browser versions.
- Supports various date libraries for generating groups, including the ability to use custom ones.

## Installation

Install the package via NPM using the following command:

```bash
npm install timezone-groups
```

## Usage

### `groupByOffset`

```javascript
import { groupByOffset } from "timezone-groups/groupByOffset";
import { DateEngine } from "timezone-groups/groupByOffset/strategy/native";

const timeZoneGroups = await groupByOffset({
  startDate, // The start reference date to generate the groups (defaults to now).
  groupDateRange, // The number of days to consider for the DST groupings (defaults to 365).
  dateEngine: new DateEngine(), // The date engine instance used to generate groups. You can use the `createDateEngine` utility to create an engine from any of the supported engine values. Alternatively, a custom date engine instance used to generate groups.
});

console.log(timeZoneGroups);

// Output:
// [
//   {
//     "labelIdx": [0, ..., 46],
//     "tzs": ["America/Anguilla", ...,  "America/Tortola"]
//   },
// ...
// ]
```

### `groupByName`

```javascript
import { groupByName } from "timezone-groups/groupByName";

const timeZoneGroups = await groupByName();

console.log(timeZoneGroups);

// Output:
// [
//   {
//     "label": "Africa/Abidjan",
//   },
//   {
//     "label": "Africa/Accra",
//   },
// ...
// ]
```

### `groupByRegion`

```javascript
import { groupByRegion } from "timezone-groups/groupByRegion";

const timeZoneGroups = await groupByRegion();

console.log(timeZoneGroups);

// Output:
// [
//   {
//     "label": "Africa",
//     "tzs": ["Africa/Abidjan", ...,  "Africa/Windhoek"]
//   },
//   {
//     "label": "America",
//     "tzs": ["America/Adak", ...,  "America/Yakutat"]
//   },
// ...
// ]
```

## Notes

- IANA time zones are generated via `Intl.supportedValuesOf("timeZone")`.
- Label indices can be used to provide localized labels.
- Based on https://github.com/neogermi/timezone-grouping/ (many thanks to [@neogermi](https://github.com/neogermi)).

---
_Source: https://npm.io/package/timezone-groups · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._