# xinjs-timezone-picker

> a lightweight, mobile-friendly, self-contained timezone-picker web-component

Latest version **0.4.3** (published 2023-08-20) · MIT license · 0 weekly downloads

## Install

```sh
npm install xinjs-timezone-picker
pnpm add xinjs-timezone-picker
yarn add xinjs-timezone-picker
bun add xinjs-timezone-picker
```

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.4.3 |
| Published | 2023-08-20 |
| First published | 2023-07-01 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 1 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Tonio Loewald |
| Maintainers | tonioloewald |
| Keywords | xinjs, web-components, javascript, typescript, timezones, timezone-picker |

## Links

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

## Alternatives

- [@js-joda/timezone](https://npm.io/package/@js-joda/timezone.md) — 383.4K weekly downloads
- [chartjs-adapter-moment](https://npm.io/package/chartjs-adapter-moment.md) — 210.8K weekly downloads
- [strftime](https://npm.io/package/strftime.md) — 171.2K weekly downloads
- [vue-flatpickr-component](https://npm.io/package/vue-flatpickr-component.md) — 115.8K weekly downloads
- [timepicker](https://npm.io/package/timepicker.md) — 51.0K weekly downloads

## Recent versions

- 0.4.3 (latest) — 2023-08-20
- 0.4.2 — 2023-08-20
- 0.4.1 — 2023-07-06
- 0.4.0 — 2023-07-01
- 0.3.0 — 2023-07-01
- 0.2.0 — 2023-07-01
- 0.1.0 — 2023-07-01

## README

# xinjs-timezone-picker

[demo](https://tonioloewald.github.io/xinjs-timezone-picker/) | [github](https://github.com/tonioloewald/xinjs-timezone-picker#readme) | [npm](https://www.npmjs.com/package/xinjs-timezone-picker) | ![bundlejs](https://deno.bundlejs.com/?q=xinjs-timezone-picker&badge=)

Copyright ©2023 Tonio Loewald

This is a [web-component](https://developer.mozilla.org/en-US/docs/Web/API/Web_components) 
that provides a graphical timezone-picker, inspired by Apple's graphical timezone-picker.

`<timezone-picker>` has been made as compact and fast-loading as possible, by keeping the geometry to a minimum,
computing as using data provided by `Intl` where possible, and generating the underlying SVG
data on-the-fly.

The widget is designed so that the `value` of the `<timezone-picker>` element will always
be a valid IANA timezone name, and it supports both a graphical picker and `autocomplete`
based on the timezone name *and* the GMT offset, so you can get to "America/Los_Angeles"
by typing "Los" or "-7".

## Usage

### HTML

    import 'xin-timezone-picker'

And now you can use:

    <timezone-picker timezone="Australia/Sydney"></timezone-picker>

### Programmatically

    import { timezonePicker } from 'xin-timezone-picker'
    document.body.append(timezonePicker())

`timezonePicker` is a standard `xinjs` `ElementCreator`, i.e. a function that takes
`ElementPart` parameters and returns an `element` of the type expected.

You can also obtain TimezonePicker, the class constructor for `<timezone-picker>`.

### timezones, localTimezone, Timezone

Rather than using a static dataset of timezones, <timezone-picker> uses the 
[Intl](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl)
Javascript global to build `timezones` and determine the `localTimezone`. This
both reduces the size of this component considerably and ensures it will match
the behavior of the runtime environment exactly.

These are respectively of type `Timezone[]` and a `Timezone`, where:

    interface Timezone {
      name: string    // the IANA name
      offset: number  // the offset from GMT in hours
      utc: string     // the timezone's UTC offset
    }

> Note that for some reason `parcel` is not recognizing that the `Timezone` interface is
> exported, so it's not exported.

## Styling

You can style the <timezone-picker> by using [CSS-Variables](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_cascading_variables)

By default, the <timezone-picker> is 400px wide and 231px tall.

`--scale` scales the map as a whole.

`--map-ocean` and `--map-land` set the map colors.

`--active-color`, `--hover-opacity`, `--active-opacity` set the timezone colors.

`--hover-transition` controls the animated transition of the timezones.

`--inset`, `--padding`, `--input-bg`, `--input-radius`, position the timezone `<input>`.

`--font-size`, `--font-color`, and `--font-family` control the text of the `<input>`

## Acknowledgements

I've built on data I found in Keval Bhatt's excellent jQuery-based picker,
found here https://github.com/kevalbhatt/timezone-picker

These things are a huge pain-in-the-ass to get right, and I actually ditched
an SVG file I had paid to have built in favor of Keval's data. Bravo!

If you want to vastly improve this widget, a good place to start looking is
[IANA's web page](https://data.iana.org/time-zones/tz-link.html) which discusses
not only their data, but other sources, and links to tools to build your own.

Fundamentally, there are tools out there to build GeoJSON layers for timezones
and, combined with a fairly simple transformation (if you want to overlay one
a compressed projection vs. on, say, a mapbox view), would give you the exact
correct polygon data. The `polygons` module could then be used to simplify the
polygons (the raw GeoJSON data is over 100MB!).

This is the approach I'd take if someone were actually paying me for this…

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