Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/ndom91/react-timezone-select

🌐 An extremely usable and dynamic React timezone selector
https://github.com/ndom91/react-timezone-select

component hacktoberfest react select timezone typescript

Last synced: 6 days ago
JSON representation

🌐 An extremely usable and dynamic React timezone selector

Awesome Lists containing this project

README 

        
# 🌐⌚ react-timezone-select



[![npm](https://img.shields.io/npm/v/react-timezone-select?style=flat-square)](https://www.npmjs.com/package/react-timezone-select)

[![NPM Downloads](https://img.shields.io/npm/dm/react-timezone-select?style=flat-square)](https://www.npmjs.com/package/react-timezone-select)

[![Skypack](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg?style=flat-square)](https://skypack.dev/view/react-timezone-select)

[![Test CI](https://flat.badgen.net/github/checks/ndom91/react-timezone-select/main?style=flat-square&label=tests)](https://github.com/ndom91/react-timezone-select/actions?query=workflow%3A%22Tests+CI%22)

[![MIT](https://flat.badgen.net/badge/license/MIT/blue?style=flat-square)](https://github.com/ndom91/react-timezone-select/blob/main/LICENSE)



Another react timezone select component, I know.. However this one has a few key benefits!



While looking around for a good option, I had trouble finding a timezone select components which:



1. Adjusted the choices automatically with Daylight Savings Time (DST)

2. Didn't have a huge list of choices to scroll through when technically only 24 (ish) are necessary



> [!IMPORTANT]

>

> ### Demo: [ndom91.github.io/react-timezone-select](https://ndom91.github.io/react-timezone-select/)

>

> This demo is also available in the `./examples` directory. Simply run `pnpm dev` in the root of the repository and the vite dev server will start, where you can then find the example app at [`localhost:3001`](http://localhost:3001).



## 🏗️ Installing



```bash

npm install react-timezone-select react-select

```



> [!CAUTION]

> The package `react-select` is optional. It is unnecessary if you're only using [the hook](#-timezone-hook).



## 🔭 Usage



```tsx

import React, { useState } from "react"

import ReactDOM from "react-dom"

import TimezoneSelect, { type ITimezone } from "react-timezone-select"



const App = () => {

  const [selectedTimezone, setSelectedTimezone] = useState(

    Intl.DateTimeFormat().resolvedOptions().timeZone,

  )



  return (

    


      
react-timezone-select


      
Please make a selection


      


        

      


      
Output:


      


        

          {JSON.stringify(selectedTimezone, null, 2)}

        


      


    


  )

}



const rootElement = document.getElementById("root")

ReactDOM.render(, rootElement)

```



## 🎨 Timezone Hook



By default, `react-timezone-select` uses [`react-select`](https://github.com/jedwatson/react-select) as underlying select component. If you'd like to bring your own select component, you can use the `useTimezoneSelect` hook instead of the `TimezoneSelect` component to render the timezones using your self-provided select component.



```tsx

import { useTimezoneSelect, allTimezones } from "react-timezone-select"



const labelStyle = "original"

const timezones = {

  ...allTimezones,

  "Europe/Berlin": "Frankfurt",

}



const customSelect = () => {

  const { options, parseTimezone } = useTimezoneSelect({ labelStyle, timezones })



  return (

     onChange(parseTimezone(e.currentTarget.value))}>

      {options.map((option) => (

        {option.label}

      ))}

    

  )

}

```



## 🕹️ Props



  

    

      Prop

      Type

      Default

      Note

    

    

      value

      string | ITimezoneOption

      null

      Initial/current Timezone

    

    

      onBlur

      () => void

      null

      

    

    

      onChange

      (timezone: ITimezoneOption) => void

      null

      

    

    

      labelStyle

      'original' | 'altName' | 'abbrev' | 'offsetHidden'

      'original'

      

    

    

      displayValue

      'GMT' | 'UTC'

      'GMT'

      Prefix for the label (i.e. "(GMT+2:00)" or "(UTC+2:00)")

    

    

      timezones

      Record

      allTimezones

      

    

    

      currentDatetime

      Date | string

      null

      Override datetime used to calculate timezone values (alternative to current datetime), useful for calculating different summer / winter times, etc.

    

  



#### Example `value`s:



```ts

// string

value='America/Juneau'

// ITimezoneOption; i.e. `onChange` return value

value={{

  value: 'America/Juneau'

  label: '(GMT-8:00) Alaska,

  abbrev: 'AHST',

  offset: -8,

  altName: 'Alaskan Standard Time'

}}

```



#### Example `timezones`:



```ts

timezones={{

  ...allTimezones,

  'America/Lima': 'Pittsburgh',

  'Europe/Berlin': 'Frankfurt',

}}

```



## ✨ Tips



### 👤 Default Users Timezone



If you'd like the user's own timezone to be set as the initially selected option on render, we can make use of the new `Intl` browser API by setting the default state value to `Intl.DateTimeFormat().resolvedOptions().timeZone`.



```tsx

const [timezone, setTimezone] = useState(Intl.DateTimeFormat().resolvedOptions().timeZone)

```



### 🕒 Custom Timezones



You can append custom choices of your own, or fully replace the listed timezone options.



The `timezones` prop takes a dictionary of timezones in the format of "`{ tzIdentifier: Label }`" ([Timezone Identifiers](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)). 



```tsx

import TimezoneSelect, { type ITimezone, allTimezones } from 'react-timezone-select'



const [selectedTimezone, setSelectedTimezone] = useState('Europe/Berlin')



```



The example above will include all original timezones and generate two additional choices:



- `'(GMT-5:00) Pittsburgh'`

- `'(GMT+1:00) Frankfurt'`



We'll prepend the correct `(GMT...)` part to the generated label, you just have to provide the string you want in your label. Also, you can omit spreading in the `allTimezones` object for a select dropdown consisting of only your custom choices.



## 🚧 Contributing



Pull requests are always welcome! Please stick to repo formatting/linting settings, and if adding new features, please consider adding test(s) and documentation where appropriate!



## 🙏 Thanks



- [All Contributors](https://github.com/ndom91/react-timezone-select/graphs/contributors)

- [Carlos Matallin](https://github.com/matallo/)

- [spacetime](https://github.com/spencermountain/spacetime)

- [react-select](https://react-select.com)



## 📝 License



MIT